By name: arch description: >- FlexPrice repo architecture — docs/ layering, deps, hotspots, flows, Graphify. Say arch, repo architecture, FLEXPRICE structure, onboarding codebase.
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&startTemporalWorkerbranches). - Locate the bounded context — map feature → domain package (
internal/domain/<ctx>) → repository impl (repository/entvsrepository/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
GetGlobalTemporalServicewith 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.