AGENTS.md

AGENTS.md

DDD-first operating guide for coding agents in this repository.

1) Core Principle

Model behavior around the domain first. Protect domain language, business invariants, and bounded-context boundaries before optimizing frameworks, transport, or storage.

2) Bounded Contexts (Monorepo Map)

The boundaries/ directory represents bounded contexts and related interfaces:

• link (Go) - core short-link lifecycle domain
• metadata (Go) - enrichment and screenshot/metadata domain
• bff (Go) - client-facing application/API composition for web
• api/api-gateway (Go) - deprecated API boundary context
• proxy (TypeScript) - redirect/runtime edge service
• ui (Next.js/TypeScript) - web client
• mobile (Expo + Nx) - mobile client
• chrome-extension (WXT + React/TS) - browser client

Read first:

• boundaries/README.md
• boundary-local README.md
• docs/ADR/README.md

3) Rule Precedence (Most Specific Wins)

If instructions conflict, follow:

1. Files in the exact service/context being edited
2. Boundary-local rules:
   • boundaries/proxy/.cursor/rules/architecture.md
   • boundaries/ui/.cursor/rules/front-end-cursor-rules.mdc
3. Repo-wide rules:
   • .cursor/.cursorrules
   • .cursor/rules/go-microservices.mdc
4. This document

4) DDD Architecture Rules

4.1 Layer Responsibilities

• Domain layer
  • Entities, Value Objects, Aggregates, Domain Services, Domain Events
  • No infrastructure dependencies
  • Business invariants enforced here
• Application layer
  • Use cases/application services
  • Orchestrates domain behavior and transactions
  • DTOs for boundary contracts
• Infrastructure layer
  • DB, MQ, HTTP clients, file systems, third-party SDKs
  • Implements repository/gateway interfaces
• Interface/transport layer
  • HTTP/gRPC handlers, CLI, messaging consumers
  • Map external contracts to application DTOs

Dependency direction must always point inward (toward domain).

4.2 Tactical DDD Guidance

• Keep aggregate roots small and consistency-focused.
• Modify aggregate state only through aggregate behavior.
• Prefer immutable Value Objects.
• Repositories should load/save aggregate roots, not random tables.
• Domain events should express business facts in ubiquitous language.
• Cross-context integration should use explicit contracts (events, APIs, ACL/adapters), never hidden coupling.

4.3 Ubiquitous Language

• Use terms from boundary glossary/README/ADR in names.
• If domain meaning changes, update docs and naming in the same PR.
• Avoid generic names like manager, data, util for domain logic.

5) Agent Workflow (DDD-Oriented)

1. Identify the target bounded context.
2. Identify affected aggregate/use case.
3. Write change at domain/application level first; adapt infra second.
4. Keep changes local to one context unless integration is required.
5. Validate with the narrowest relevant tests/checks.
6. Summarize domain impact (invariant, event, contract, behavior).

6) Commands (Validated in this repo)

Root

• make help
• make dep
• make up / make down (heavy full stack)

There are no proto targets at the root: every .proto lives inside a boundary that owns its own buf module. Run them from the boundary, e.g. make -C boundaries/link proto-check.

Go contexts

Run from context directory:

• go test ./...
• go test -run <Name> ./...
• make help

Useful local targets:

• boundaries/link: make dev, make docs, make e2e, plus the proto targets below
• boundaries/metadata: proto targets below, docs via make help
• boundaries/bff: make dep, make generate, make docs

Proto targets, identical in boundaries/link and boundaries/metadata (require the buf CLI — brew install bufbuild/buf/buf):

• make proto-check — lint + format + breaking, the same three checks CI runs
• make proto-lint, make proto-format (proto-format-fix to rewrite)
• make proto-breaking — compares the module against its state on main
• make proto-generate — regenerate .pb.go
• make proto-push — publish the module to the BSR; manual, never done by CI
• make proto-dep-update — refresh buf.lock

TypeScript/Frontend contexts

• boundaries/proxy: pnpm install && pnpm build && pnpm lint && pnpm test
• boundaries/ui: pnpm install && pnpm type-check && pnpm lint && pnpm test:run
• boundaries/mobile: pnpm install && pnpm nx serve shortlink (or pnpm nx build shortlink)
• boundaries/chrome-extension: pnpm install && pnpm build && pnpm compile

7) Generation and Contracts

• Contracts are distributed through the BSR. A boundary publishes its own module; consumers depend on the generated SDK (buf.build/gen/go/... in go.mod, @buf/... in package.json). Never copy someone else's .proto into your boundary and never generate their contract locally.
• When a .proto changes, the order is: make proto-check → make proto-generate → commit → manually make -C <boundary> proto-push → consumers pull the new SDK via go get / pnpm update.
• Regenerated code is committed in the same change as the contract it comes from.
• Regenerate derived artifacts in the same change when contracts/interfaces change.
• Do not hand-edit generated files unless unavoidable; document reason when doing so.

8) Anti-Patterns (Avoid)

• Business logic inside handlers/controllers/repositories.
• Infrastructure types leaking into domain entities/value objects.
• Cross-context direct DB coupling.
• “God” services that bypass aggregate invariants.
• Renaming domain concepts without updating ubiquitous language docs.

9) Git Hygiene

• Check current tree before editing: git status.
• Keep commits small and domain-focused.
• Use clear English commit messages.
• Never revert unrelated user changes.

10) Definition of Done (DDD Checklist)

Before finalizing:

• Bounded context and aggregate boundaries were respected.
• Domain invariants are preserved and tested.
• External contracts/events are updated and validated if changed.
• Relevant tests/lint/type-check were run (or explicitly justified).
• ADR/README/glossary updates are included when domain language changed.