Kyle Isom
24a0db0f47
- Remove deprecated mcdeploy/ from project map (directory doesn't exist) - Add log/ directory to project map - Update MCP description to reflect multi-node fleet management - Add note about subprojects at sibling paths (mcat, mcdoc, mcq) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
89 lines
5.1 KiB
Markdown
89 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Overview
|
|
|
|
Metacircular is a multi-service personal infrastructure platform. This root repository is a workspace container — each subdirectory is a separate Git repo (gitignored here). The authoritative platform-wide standards live in `engineering-standards.md`.
|
|
|
|
## Project Map
|
|
|
|
| Directory | Purpose | Language |
|
|
|-----------|---------|----------|
|
|
| `mcias/` | Identity and Access Service — central SSO/IAM, all other services delegate auth here | Go |
|
|
| `metacrypt/` | Cryptographic service engine — encrypted secrets, PKI/CA, SSH CA, transit encryption | Go |
|
|
| `mc-proxy/` | TLS proxy and router — L4 passthrough or L7 terminating, PROXY protocol, firewall | Go |
|
|
| `mcr/` | OCI container registry — integrated with MCIAS for auth and policy-based push/pull | Go |
|
|
| `mcat/` | MCIAS login policy tester — lightweight web app to test and audit login policies | Go |
|
|
| `mcdsl/` | Standard library — shared packages for auth, db, config, HTTP/gRPC servers, CSRF, snapshots | Go |
|
|
| `mcdoc/` | Documentation server — renders markdown from Gitea, serves public docs via mc-proxy | Go |
|
|
| `mcq/` | Document review queue — push docs for review, MCP server for Claude integration | Go |
|
|
| `mcp/` | Control plane — service deployment, container lifecycle, multi-node fleet management (CLI/agent, master in development) | Go |
|
|
| `mcns/` | Networking service — custom Go DNS server, authoritative for internal zones | Go |
|
|
| `ca/` | PKI infrastructure and secrets for dev/test (not source code, gitignored) | — |
|
|
| `docs/` | Platform-wide documentation (architecture overview, deployment guide) | Markdown |
|
|
| `log/` | Operational work logs and session notes | Markdown |
|
|
|
|
Each subproject has its own `CLAUDE.md`, `ARCHITECTURE.md`, `Makefile`, and `go.mod`. When working in a subproject, read its own CLAUDE.md first.
|
|
|
|
Some subprojects (mcat, mcdoc, mcq) may live at sibling paths (e.g., `../mcq/`) rather than as subdirectories, depending on workspace layout.
|
|
|
|
## Service Dependencies
|
|
|
|
MCIAS is the root dependency — every other service authenticates through it. No service maintains its own user database. The dependency graph:
|
|
|
|
```
|
|
mcias (standalone — no MCIAS dependency)
|
|
├── metacrypt (uses MCIAS for auth)
|
|
├── mc-proxy (uses MCIAS for admin auth)
|
|
├── mcr (uses MCIAS for auth + policy)
|
|
├── mcdoc (public, no MCIAS — fetches docs from Gitea)
|
|
├── mcq (uses MCIAS for auth; document review queue)
|
|
├── mcp (uses MCIAS for auth; orchestrates deployment and lifecycle)
|
|
├── mcns (uses MCIAS for auth; authoritative DNS for internal zones)
|
|
└── mcat (tests MCIAS login policies)
|
|
```
|
|
|
|
## Standard Build Commands (all subprojects)
|
|
|
|
```bash
|
|
make all # vet → lint → test → build (the CI pipeline)
|
|
make build # go build ./...
|
|
make test # go test ./...
|
|
make vet # go vet ./...
|
|
make lint # golangci-lint run ./...
|
|
make proto # regenerate gRPC code from .proto files
|
|
make proto-lint # buf lint + buf breaking
|
|
make devserver # build and run locally against srv/ config
|
|
make docker # build container image
|
|
make clean # remove binaries
|
|
```
|
|
|
|
Run a single test: `go test ./internal/auth/ -run TestTokenValidation`
|
|
|
|
## Critical Rules
|
|
|
|
1. **REST/gRPC sync**: Every REST endpoint must have a corresponding gRPC RPC, updated in the same change.
|
|
2. **gRPC interceptor maps**: New RPCs must be added to `authRequiredMethods`, `adminRequiredMethods`, and/or `sealRequiredMethods`. Forgetting this is a security defect.
|
|
3. **No CGo in production**: All builds use `CGO_ENABLED=0`. Use `modernc.org/sqlite`, not `mattn/go-sqlite3`.
|
|
4. **No test frameworks**: Use stdlib `testing` only. Real SQLite in `t.TempDir()`, no mocks for databases.
|
|
5. **Default deny**: Unauthenticated and unauthorized requests are always rejected. Admin detection comes solely from the MCIAS `admin` role.
|
|
6. **Proto versioning**: Start at v1. Only create v2 for breaking changes. Non-breaking additions go in-place.
|
|
|
|
## Architecture Patterns
|
|
|
|
- **Seal/Unseal**: Metacrypt starts sealed and requires a password to unlock (Vault-like pattern). Key hierarchy: Password → Argon2id → KWK → MEK → per-engine DEKs.
|
|
- **Web UI separation**: Web UIs run as separate binaries communicating with the API server via gRPC. No direct DB access from the web tier.
|
|
- **Config**: TOML with env var overrides (`SERVICENAME_*`). All runtime data in `/srv/<service>/`.
|
|
- **Policy engines**: Priority-based ACL rules, default deny, admin bypass. See metacrypt's implementation as reference.
|
|
- **Auth flow**: Client → service `/v1/auth/login` → MCIAS client library → MCIAS validates → bearer token returned. Token validation cached 30s keyed by SHA-256 of token.
|
|
|
|
## Tech Stack
|
|
|
|
- Go 1.25+, chi router, cobra CLI, go-toml/v2
|
|
- SQLite via modernc.org/sqlite (pure Go), WAL mode, foreign keys on
|
|
- gRPC + protobuf, buf for linting
|
|
- htmx + Go html/template for web UIs
|
|
- golangci-lint v2 with errcheck, gosec, staticcheck, revive
|
|
- TLS 1.3 minimum, AES-256-GCM, Argon2id, Ed25519
|