// FlexPrice repo architecture — docs/ layering, deps, hotspots, flows, Graphify. Say arch, repo architecture, FLEXPRICE structure, onboarding codebase.
Dev environment wizard — hybrid by default: .env/.env.local creds for RDS, managed Kafka, etc.; Docker only for components the user says are local; idempotent Compose checks when applicable; **Local Compose:** always use localhost creds (**§C1** in `.env.local`) before migrations, seeds, `go run`/run-local-*; **Effort → model (**§M**):** classify S/M/L, use fast models for checklist work, escalate to **Claude Sonnet 4.x (e.g. 4.7 when offered)** / strongest reasoning tier for hybrid/RDS churn; **Parallelism (**§N**):** spawn **Cursor Task subagents** for independent probes or read-only investigate paths when it speeds **§F** convergence. Kafka: prompt before default-topic creation (**`make init-kafka`**). Modes api/consumer/temporal_worker/local. Trigger: devenv, local dev, run-local.
Master HTTP QA: chains devenv then interactive API key / X-Environment-ID then real curls. Shards suites to parallel workers. Trigger: apitest, api test, curl localhost, QA local API.
FlexPrice Docker/Makefile shortcuts — dev-setup, compose services, Kafka UI profile, logs. Deep env wizard is devenv. Trigger: compose, docker dev, dev-setup.
gh CLI for FlexPrice repos — PRs, checks, issues. Trigger: gh, github pr.
FlexPrice Go fmt, vet, race tests, make test. Trigger: godev, run tests, go vet.
Swagger + Speakeasy SDK/MCP pipeline (make swagger, sdk-all), api/custom merge. Trigger: openapi, swagger, sdk-all, MCP.
| name | arch |
| description | FlexPrice repo architecture — docs/ layering, deps, hotspots, flows, Graphify. Say arch, repo architecture, FLEXPRICE structure, onboarding codebase. |
arch — repository architectureUse 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).
| 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.
cmd/server/main.go + deployment.mode. Determine whether edits affect API-only paths, Kafka consumers, or Temporal workers (registerRouterHandlers & startTemporalWorker branches).internal/domain/<ctx>) → repository impl (repository/ent vs repository/clickhouse) → service (internal/service/<file>) → handler (internal/api/v1).internal/config) and Temporal workflow names (internal/temporal/workflows).ServiceParams, consider narrowing new code’s dependencies deliberately.docs/DEPENDENCY_GRAPH.md).internal/temporal/registration.go).GetGlobalTemporalService with injected interfaces when editing those call sites safely.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.
subscription.go, invoice.go, billing.go).make generate-ent + deliberate migration rollout; annotate operational risk if backfill jobs required.internal/pubsub/router).