Imported from meerita/monorepo-nextjs-golang-rust-python-ai-rules (
services/api/AGENTS.md). Install upstream withnpx skills add meerita/monorepo-nextjs-golang-rust-python-ai-rules --skill api. Copyright stays with the author.
Agent Instructions — services/api (Go)
Read the root AGENTS.md and the applicable universal rules in
../../.agents/rules/ before this file.
Service overview
services/api is the Go modular monolith — the business core and the source of
truth for served state (organizations, users, roles, projects, data sources, the
job queue, the outbox, and published snapshots: findings, scores, explanations). It
also hosts the MCP server consumed by the AI layer. It owns the Go DB. Identity,
LLM, and embedding logic do not live here (see ../../.agents/rules/01-project-boundaries.md).
Two listeners, one composition root
Go process
├── :8080 business API (fasthttp) ← consumed by the frontend
└── :8090 MCP server (net/http) ← consumed by the Python AI client
Both start from cmd/api. The MCP tools are an inbound adapter over the same
use cases the HTTP handlers call — not a parallel path.
Service map
cmd/api/ process entry + composition root (main, bootstrap, modules, server)
internal/http/ INBOUND adapter — fasthttp business API (:8080)
internal/mcp/ INBOUND adapter — MCP server (:8090), consumed by the AI layer
internal/modules/ INNER — one package per bounded context (domain/ports/application)
internal/platform/ OUTBOUND adapters + cross-cutting infra (config, database, event, identity, storage, uuid)
migrations/ goose migrations, owned by services/api only
tests/ unit, integration, e2e
Command surface
make check # build + vet + fmt-check (run after every change set)
make fmt / make fmt-check
make lint
make test / make test-unit
make test-up / make test-integration / make test-e2e / make test-down
make migrate-up / make migrate-status # goose via `go tool`
make runtest-up/test-down/test-integration delegate to the root Make targets — the
centralized, ephemeral backing infrastructure on the +10 port band. This service
must not define its own Docker or compose. See ../../docker/AGENTS.md.
Rules to read
Universal backend rules (read before the service rules when relevant):
| Universal rule | File |
|---|---|
| Persistence and PostgreSQL | ../../.agents/rules/20-persistence-and-postgresql.md |
| Query services and read models | ../../.agents/rules/21-query-services.md |
| Transactions | ../../.agents/rules/22-transactions.md |
| Migrations (universal) | ../../.agents/rules/23-migrations.md |
| Security and compliance | ../../.agents/rules/24-security-and-compliance.md |
| Identifiers and UUIDv7 | ../../.agents/rules/18-identifiers-and-uuidv7.md |
| LLM data boundary and code egress | ../../.agents/rules/19-llm-data-boundary-and-code-egress.md |
Service-specific rules:
| Rule | File |
|---|---|
| Architecture | .agents/rules/02-architecture.md |
| Dependency policy | .agents/rules/03-dependency-policy.md |
| Testing | .agents/rules/06-testing.md |
| Go standards | .agents/rules/07-go-standards.md |
| Errors, HTTP, and MCP mapping | .agents/rules/08-errors-and-http-mapping.md |
| Authorization and roles | .agents/rules/09-authorization-and-roles.md |
| Security and data handling | .agents/rules/10-security-and-data-handling.md |
| Config and environment | .agents/rules/13-config-and-environment.md |
| Migrations (goose) | .agents/rules/21-migrations.md |