arch — repository architecture
Use when navigating cmd/, internal/, ent/ (billing, metering, Temporal, Kafka, integrations).
Other repos: repo-architecture-intelligence (~/.cursor/skills/repo-architecture-intelligence/SKILL.md).
Sibling skills: README (apitest, devenv, godev, openapi, pr, gh, compose).
Canonical documentation map
| Doc | Purpose |
|---|
docs/REPO_MAP.md | Directory census, deployment modes, major systems |
docs/ARCHITECTURE.md | Principles, infra choices, layering, conventions |
docs/DEPENDENCY_GRAPH.md | Fan-in/out, messaging DAG, coupling notes |
docs/HOTSPOTS.md | Large files & structural risks |
docs/FLOWS/*.md | End-to-end narratives for critical paths |
Rule: Prefer these artifacts over improvised mental models. If docs drift from code during your change, patch the relevant markdown.
How to analyze architecture quickly
- Identify deployment surface —
cmd/server/main.go + deployment.mode. Determine whether edits affect API-only paths, Kafka consumers, or Temporal workers (registerRouterHandlers & startTemporalWorker branches).
- Locate the bounded context — map feature → domain package (
internal/domain/<ctx>) → repository impl (repository/ent vs repository/clickhouse) → service (internal/ee/service/<file>) → handler (internal/api/v1).
- Check async edges — list Kafka topics touched (search config keys under
internal/config) and Temporal workflow names (internal/temporal/workflows).
- Assess coupling — if you need half of
ServiceParams, consider narrowing new code’s dependencies deliberately.
How to reason about dependencies
- Follow canonical direction: handlers → services → (domain interfaces + repos/integrations) → storage/IO (see diagram in
docs/DEPENDENCY_GRAPH.md).
- Watch logical cycles: Temporal registration reconstructs some services independently of Fx (
internal/temporal/registration.go).
- Question globals: prefer replacing new uses of
GetGlobalTemporalService with injected interfaces when editing those call sites safely.
How to persist repository memory
After meaningful structural edits:
| Change type | Update |
|---|
| New package / major subsystem | REPO_MAP.md (+ ARCHITECTURE.md boundaries if philosophical) |
| New topic/consumer or coupling | DEPENDENCY_GRAPH.md + YAML pointer |
| Emerging risk/god file growth | HOTSPOTS.md entry |
| Flow behavior change | Relevant docs/FLOWS/<name>.md |
Treat docs as durable context for future automation and onboarding.
How to refactor safely
- Freeze scope — isolate one bounded context or one pipeline stage.
- Add or extend characterization tests closest to seams you cut (heavy services deserve targeted tests despite size).
- Avoid splitting multi-thousand-line files blindly — extract cohesive types/helpers with stable interfaces (
subscription.go, invoice.go, billing.go).
- For schema changes — always
make generate-ent + deliberate migration rollout; annotate operational risk if backfill jobs required.
- For messaging — verify consumer group uniqueness and DLQ configuration when adjusting handler semantics (
internal/pubsub/router).
Anti-patterns to flag during review
- Domain importing repositories or Gin types.
- Handlers querying Ent directly.
- Silent topic renames without consumer coordination.
- New global singletons hiding dependencies.