docs: Update AGENTS.md #22
Conversation
- Document service layout, tooling, and workflows - Capture messaging, testing, and security guidance
Completed Working on "Auto PR Description"✅ Workflow completed successfully. |
Completed Working on "Auto PR Description"✅ Workflow completed successfully. |
![overcut-ai[bot]](https://avatars.githubusercontent.com/in/1367736?s=60&v=4){kind=small}
There was a problem hiding this comment.
Summary: 5 MAJOR findings (0 BLOCKER, 0 CRITICAL, 0 MINOR, 0 SUGGESTION, 0 PRAISE).
Key themes:
- Service environment tables omit required Kafka/NATS variables or misname actual build-time keys, so operators following this doc will end up with broken deployments.
- Messaging guidance over-promises: the logistic server guide claims Kafka + NATS wiring/handlers that are not implemented, which misleads anyone relying on those subscribers.
- Several sections describe runtime behaviors (connectMicroservices, handler coverage) that don’t exist in code today, creating a dangerous drift between reference doc and application reality.
Next steps:
- Update the ecommerce-server, logistic-server, and ecommerce-admin env var tables to list the real variables enforced by code (
KAFKA_*,NATS_SERVERS,VITE_REACT_APP_SERVER_URL, etc.) with accurate defaults. - Align the messaging/connectivity sections with the actual implementation—either add the missing NATS handlers/microservice wiring or clearly document that they are not available yet.
- Re-read the rest of AGENTS.md for similar discrepancies so the reference stays authoritative for automation and new contributors.
AGENTS.md
Outdated
| | Name | Description | Default / Notes | Source | | ||
| | --- | --- | --- | --- | | ||
| | `PORT` | Frontend dev server port | `3001` | `apps/ecommerce-admin/README.md` | | ||
| | `REACT_APP_SERVER_URL` | Base URL for backend API | `http://localhost:[server-port]` | same | |
There was a problem hiding this comment.
[major]: Frontend env var name is wrong
AGENTS.md repeatedly tells contributors to set REACT_APP_SERVER_URL for the admin app, but the Vite client reads import.meta.env.VITE_REACT_APP_SERVER_URL (matching apps/ecommerce-admin/.env). Following the doc leaves the dashboard pointing at undefined. Rename those references to VITE_REACT_APP_SERVER_URL and note that Vite exposes it via import.meta.env.
Suggested fix: Replace each REACT_APP_SERVER_URL reference (tables + workflow steps) with VITE_REACT_APP_SERVER_URL and explain Vite access.
AGENTS.md
Outdated
| - **Kafka topics (from `README.md`):** `order.create.v1`, `order.update.v1`, `product.create.v1`, `product.update.v1`. | ||
| - `apps/ecommerce-server` sends messages on those topics (see `src/kafka/kafka.producer.service.ts`). | ||
| - `apps/logistic-server` consumes the same topics (`src/kafka/kafka.service.ts`). | ||
| - **NATS (logistics):** `apps/logistic-server/docker-compose.dev.yml` defines a `nats` container, and the service implements handlers in `src/nats/` (`nats.module.ts`, `nats.service.ts`, `topics.ts`). Kafka and NATS clients are wired in `src/connectMicroservices.ts`. |
There was a problem hiding this comment.
[major]: NATS wiring description inaccurate
The Messaging section claims Kafka and NATS clients are wired in apps/logistic-server/src/connectMicroservices.ts, but that file only registers Kafka. NATS is configured solely through Nest modules, so the guide sends readers on a goose chase for nonexistent bootstrap code.
Suggested fix: Rephrase to say only Kafka is wired via connectMicroservices.ts (or actually add the NATS hookup if intended).
AGENTS.md
Outdated
| 2. **Install dependencies** with `npm install` inside that service. | ||
| 3. **Generate Prisma artifacts** via `npm run prisma:generate` (backends only) when schemas change. | ||
| 4. **Provision local infra** with `npm run docker:dev` to bring up the service’s database, Kafka stack, and (for logistics) NATS & Adminer. | ||
| 5. **Initialize data** using `npm run db:init` to run migrations plus `scripts/seed.ts`. |
There was a problem hiding this comment.
[major]: db:init guidance generates new migrations
The doc instructs everyone to run npm run db:init during setup, yet that script creates a brand-new migration named 'initial version' before applying migrations. Using it routinely dirties the repo and even fails once that migration already exists. The workflow should instead tell contributors to apply existing migrations (e.g., db:migrate-up + seed) and reserve db:init for the first migration only.
Suggested fix: Update the Tooling/Common Tasks steps to recommend db:migrate-up + seed (or db:clean && db:migrate-up) for everyday setup and document db:init as a one-off when creating the initial migration.
🔄 Overcut automatically updated AGENTS.md with latest repository analysis.
Summary
This PR introduces a comprehensive
AGENTS.mdfield guide so contributors can quickly understand the monorepo’s three services, their tech stacks, and the guardrails for working with Amplication-generated assets. It consolidates environment variables, tooling commands, messaging pathways, and day-to-day workflows for the ecommerce and logistics backends plus the React Admin frontend.Changes
Commits
Testing
AGENTS.mdfor accuracy against each service’s README, package scripts, and compose files..envfiles.