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.
1---2name: arch3description: FlexPrice repo architecture — docs/ layering, deps, hotspots, flows, Graphify. Say arch, repo architecture, FLEXPRICE structure, onboarding codebase.4---56# **`arch`** — repository architecture78Use when navigating **`cmd/`**, **`internal/`**, **`ent/`** (billing, metering, Temporal, Kafka, integrations).910**Other repos:** **`repo-architecture-intelligence`** (`~/.cursor/skills/repo-architecture-intelligence/SKILL.md`).1112**Sibling skills:** [README](../README.md) (**`apitest`**, **`devenv`**, **`godev`**, **`openapi`**, **`pr`**, **`gh`**, **`compose`**).1314## Canonical documentation map1516| Doc | Purpose |17| --- | ------- |18| `docs/REPO_MAP.md` | Directory census, deployment modes, major systems |19| `docs/ARCHITECTURE.md` | Principles, infra choices, layering, conventions |20| `docs/DEPENDENCY_GRAPH.md` | Fan-in/out, messaging DAG, coupling notes |21| `docs/HOTSPOTS.md` | Large files & structural risks |22| `docs/FLOWS/*.md` | End-to-end narratives for critical paths |2324**Rule:** Prefer these artifacts over improvised mental models. If docs drift from code during your change, patch the relevant markdown.2526## How to analyze architecture quickly27281. **Identify deployment surface** — `cmd/server/main.go` + `deployment.mode`. Determine whether edits affect API-only paths, Kafka consumers, or Temporal workers (`registerRouterHandlers` & `startTemporalWorker` branches).292. **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`).303. **Check async edges** — list Kafka topics touched (search config keys under `internal/config`) and Temporal workflow names (`internal/temporal/workflows`).314. **Assess coupling** — if you need half of `ServiceParams`, consider narrowing new code’s dependencies deliberately.3233## How to reason about dependencies3435- Follow **canonical direction**: handlers → services → (domain interfaces + repos/integrations) → storage/IO (see diagram in `docs/DEPENDENCY_GRAPH.md`).36- Watch **logical cycles**: Temporal registration reconstructs some services independently of Fx (`internal/temporal/registration.go`).37- Question **globals**: prefer replacing new uses of `GetGlobalTemporalService` with injected interfaces when editing those call sites safely.3839## How to persist repository memory4041After meaningful structural edits:4243| Change type | Update |44| ----------- | ------- |45| New package / major subsystem | `REPO_MAP.md` (+ `ARCHITECTURE.md` boundaries if philosophical) |46| New topic/consumer or coupling | `DEPENDENCY_GRAPH.md` + YAML pointer |47| Emerging risk/god file growth | `HOTSPOTS.md` entry |48| Flow behavior change | Relevant `docs/FLOWS/<name>.md` |4950Treat docs as durable context for future automation and onboarding.5152## How to refactor safely53541. Freeze scope — isolate one bounded context or one pipeline stage.552. Add or extend characterization tests closest to seams you cut (heavy services deserve targeted tests despite size).563. Avoid splitting multi-thousand-line files blindly — extract cohesive types/helpers with stable interfaces (`subscription.go`, `invoice.go`, `billing.go`).574. For schema changes — always `make generate-ent` + deliberate migration rollout; annotate operational risk if backfill jobs required.585. For messaging — verify consumer group uniqueness and DLQ configuration when adjusting handler semantics (`internal/pubsub/router`).5960## Anti-patterns to flag during review6162- Domain importing repositories or Gin types.63- Handlers querying Ent directly.64- Silent topic renames without consumer coordination.65- New global singletons hiding dependencies.
flexprice