Skip to content

docs: Update AGENTS.md #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
overcut-ai wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Update AGENTS.md #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,123 @@
# 🤖 AGENTS Guide for `amplication/sample-app`

## 📦 Project Overview
Amplication generated this multi-service workspace to demonstrate an ecommerce domain split into two NestJS backends and a React admin UI. Each service is self-contained under `apps/`, but they share conventions: modular NestJS layers (`*.module.ts`, `*.service.ts`, etc.), Prisma-managed data models, Kafka (and optional NATS) messaging utilities, Jest testing, and Docker workflows for local infrastructure. Default interactive credentials across services are `admin` / `admin`.

## 🗂️ Repository Structure
```
apps/
├─ ecommerce-server/ # NestJS + PostgreSQL backend emitting Kafka events
│ ├─ src/ # Domain modules (see src/order/ for reference)
│ ├─ prisma/ # schema.prisma, migrations, Prisma scripts
│ ├─ kafka/ # messaging helpers for send pattern
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major]: The repository overview and ecommerce-server playbook describe a top-level apps/ecommerce-server/kafka/ directory, but the codebase only exposes src/kafka/. Pointing agents to a path that does not exist makes it impossible to locate the Kafka publisher templates referenced by the doc. Suggestion: Update the repo overview/ecommerce-server directory list to reference apps/ecommerce-server/src/kafka/ (and clarify that messaging helpers live under src/).

│ └─ docker-compose*.yml # local containers & brokers
├─ logistic-server/ # NestJS + MySQL backend consuming Kafka/NATS
│ ├─ src/
│ ├─ prisma/
│ ├─ kafka/ & nats/
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major]: The logistics-server summary advertises sibling apps/logistic-server/kafka/ and .../nats/ folders even though only src/kafka/ and src/nats/ exist. Following the guide sends agents hunting under directories that are not present. Suggestion: Point the repo-structure diagram and logistics-server playbook to apps/logistic-server/src/kafka/ and apps/logistic-server/src/nats/ (or otherwise state that the messaging code lives under src/).

│ └─ docker-compose*.yml
└─ ecommerce-admin/ # React + Vite + react-admin dashboard
└─ src/ (LoginForm.tsx, resources, theme)
```

## 🛠️ Development & Tooling
- **Runtime expectations:** Node.js 16+, npm, Docker (for databases/brokers), and service-specific `.env` files defining DB credentials, JWT secrets, broker URLs, and ports before running scripts.
- **Prisma data layer:** Each backend supplies `prisma/` assets plus scripts for generating clients (`npm run prisma:generate`), saving migrations, initializing (`npm run db:init`), cleaning, and seeding. Running Prisma commands requires the corresponding database container/connection to be available.
- **Messaging modules:** `kafka/` directories wire Kafka topics; `nats/` is present in the logistics app for optional NATS consumption. Respect the established send/receive semantics from the README when extending topics.
- **Docker workflows:** Prefer the provided scripts (`npm run docker:dev`, `compose:up`, `compose:down`, `package:container`) instead of ad hoc commands. They encapsulate required broker and database containers per service.
- **Frontend tooling:** The admin app uses Vite. Scripts (`start`, `build`, `serve`, `type-check`, `lint`, `format`) expect `REACT_APP_SERVER_URL` and optional `PORT` (defaults to 3001) defined in `.env`.
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major]: Both the workspace setup section here and the ecommerce-admin playbook (line 74) tell agents to export REACT_APP_SERVER_URL, but the Vite-based admin only reads import.meta.env.VITE_REACT_APP_SERVER_URL (see apps/ecommerce-admin/.env and src/data-provider/graphqlDataProvider.ts). Using the documented name leaves the GraphQL client pointing at undefined, so the dashboard cannot reach the backend. Suggestion: Replace the REACT_APP_SERVER_URL guidance with VITE_REACT_APP_SERVER_URL (and call out the Vite prefix requirement) everywhere the variable is mentioned so agents configure the environment the app actually consumes.


## 🧩 Service Playbooks
### 🧾 `apps/ecommerce-server/`
- **Purpose & stack:** Order management API (NestJS + GraphQL) backed by PostgreSQL and Kafka to emit product/order lifecycle events.
- **Key directories:** `src/order/` (baseline domain module), `prisma/` (see `schema.prisma`), `kafka/`, `scripts/`, Docker compose manifests.
- **Environment vars:** PostgreSQL DSN, Kafka broker URLs, JWT secret, HTTP port, and admin credentials stored in `.env`.
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major]: This section claims the ecommerce-server admin credentials live in .env, but apps/ecommerce-server/.env only defines DB/JWT/Kafka values while the default user/password are created in scripts/seed.ts (lines 28-33). Pointing operators to .env makes them edit a file that has no effect on the login they are trying to rotate. Suggestion: Document that the ecommerce-server admin credentials are seeded via scripts/seed.ts (and must be changed there or via Prisma) instead of referencing a non-existent .env entry.

- **Messaging topics (send pattern):** `order.create.v1`, `order.update.v1`, `product.create.v1`, `product.update.v1`.
- **NPM scripts:**
- `start`, `start:watch`, `start:debug`
- `build`
- `test`
- `seed`
- `db:migrate-save`
- `db:migrate-up`
- `db:clean`
- `db:init`
- `prisma:generate`
- `docker:dev`
- `package:container`
- `compose:up`
- `compose:down`

### 🚚 `apps/logistic-server/`
- **Purpose & stack:** Warehouse/shipment backend (NestJS + GraphQL) using MySQL, Kafka consumers, and optional NATS connectors to react to ecommerce events.
- **Key directories:** Domain modules in `src/`, `prisma/` schema + migrations, `kafka/` and `nats/` adapters, Docker compose assets (`docker-compose.dev.yml`).
- **Environment vars:** MySQL DSN, Kafka/NATS endpoints, HTTP Basic or JWT secrets, HTTP port, service credentials.
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major]: This playbook repeats that logistic-server credentials are configured in .env even though apps/logistic-server/.env mirrors the ecommerce file (only DB/JWT/Kafka/NATS values) and the admin account is created in scripts/seed.ts. The doc therefore sends agents to the wrong place when rotating credentials. Suggestion: Clarify that logistic-server credentials come from scripts/seed.ts (admin/admin by default) and must be changed in that seed process or via Prisma, not via .env variables.

- **Messaging topics (receive pattern):** `order.create.v1`, `order.update.v1`, `product.create.v1`, `product.update.v1`.
- **NPM scripts:**
- `start`, `start:watch`, `start:debug`
- `build`
- `test`
- `seed`
- `db:migrate-save`
- `db:migrate-up`
- `db:clean`
- `db:init`
- `prisma:generate`
- `docker:dev`
- `package:container`
- `compose:up`
- `compose:down`

### 🖥️ `apps/ecommerce-admin/`
- **Purpose & stack:** React-admin dashboard (React 18 + Vite + Apollo Client) consuming the ecommerce-server GraphQL endpoint.
- **Key directories:** `src/` (resources, forms, `LoginForm.tsx`), `src/api/` hooks, `src/theme/` styling assets.
- **Environment vars:** `REACT_APP_SERVER_URL` pointing to the ecommerce-server GraphQL URL; `PORT` (defaults to 3001) for the Vite dev server.
- **Messaging topics:** None directly—this UI consumes GraphQL responses already shaped by the backend events.
- **NPM scripts:**
- `start`
- `build`
- `serve`
- `type-check`
- `lint`
- `format`
- `package:container`

## 🧱 Code & Data Patterns
- NestJS modules follow Amplication conventions: each domain folder contains entity DTOs, controllers, services, resolvers, and guards with consistent naming.
- Prisma schemas live in `apps/*/prisma/schema.prisma` with migrations managed through `node_modules/.bin/prisma`. Agents should reuse the provided scripts rather than invoking Prisma directly.
- Messaging glue lives under `kafka/` (and `nats/` for logistics) with standardized publisher/subscriber services.
- React-admin resources mirror backend entities; forms/pages adopt PascalCase files and central GraphQL query definitions.

## 🧪 Quality & Validation
- Backend testing uses Jest (`npm run test`). Ensure databases or mocks are set appropriately before executing suites.
- Frontend type safety relies on `npm run type-check`; static analysis and formatting are enforced through `npm run lint` and `npm run format`.
- Container build validation is handled through `npm run package:container` in each app to confirm Dockerfiles remain functional.

## ⚠️ Critical Rules
- Never invent or seed new sample data outside the sanctioned Prisma seed scripts; extend `scripts/seed.ts` if adjustments are required.
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major]: The guardrail section instructs agents to edit scripts/seed.ts, but both backends wire their default admin accounts there and expect customization to live in scripts/customSeed.ts. Modifying seed.ts directly breaks the generated bootstrap logic and complicates future syncs. Suggestion: Direct agents to add data changes in scripts/customSeed.ts (or clearly explain the supported hook) so they extend the seed pipeline without rewriting the core script.

- Treat `.env` secrets and database credentials as sensitive—do not commit or expose values when automating.
- Respect message topic names verbatim (`order.create.v1`, etc.); renaming or inventing topics will break cross-service contracts.
- Align with README formatting cues (underlined section headers, explicit broker topic lists) when extending documentation or UX copy.

## ✅ Common Tasks
1. **Install dependencies:**
```bash
cd apps/<service>
npm install
```
2. **Bootstrap databases via Docker:** use `npm run docker:dev` (per backend) or `npm run compose:up` / `npm run compose:down` to orchestrate the DB + broker containers defined in the service.
3. **Generate Prisma client & migrations:** `npm run prisma:generate`, then `npm run db:migrate-save`, `npm run db:migrate-up`, and `npm run db:init` to apply the baseline (`db:clean` resets when needed).
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[major]: Step 3 tells agents to run db:migrate-save, db:migrate-up, and then db:init, but each backend’s db:init script already runs migrate-save/migrate-up/seed. Following the doc causes the second db:migrate-save to fail because the migration name already exists, breaking the setup workflow. Suggestion: Either have the workflow call npm run db:init by itself or document the manual migrate commands without repeating db:init, so migrations run exactly once.

4. **Seed data:** `npm run seed` after migrations (leverages `scripts/seed.ts`).
5. **Start services:** `npm run start` (NestJS) or `npm run start` (Vite) with `.env` loaded; ecommerce-admin dev server defaults to http://localhost:3001 unless `PORT` overrides.
Copy link
Author

@overcut-ai overcut-ai bot Jan 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[minor]: Line 111 says the ecommerce-admin dev server defaults to 3001 and respects PORT, but the start script runs plain vite and vite.config.ts never reads PORT, so the UI actually serves on Vite’s default 5173. Following the doc causes health checks to watch the wrong port. Suggestion: Update the workflow notes to mention the real default (5173) or describe how to override the port (e.g., via vite --port).

6. **Run tests & checks:** backends use `npm run test`; frontend uses `npm run type-check`, `npm run lint`, and `npm run format`.
7. **Build or package containers:** `npm run build` (NestJS) or `npm run build` (Vite) followed by `npm run package:container` for image validation.

## 📚 Reference Examples
- UI auth flow: `apps/ecommerce-admin/src/LoginForm.tsx`.
- Domain module baseline: `apps/ecommerce-server/src/order/`.
- Canonical Prisma schema: `apps/ecommerce-server/prisma/schema.prisma`.
- Local infrastructure template: `apps/logistic-server/docker-compose.dev.yml`.

## 🔗 Additional Resources
- Root [`README.md`](README.md) for service descriptions, underlined headings, and message topic summaries keyed to the broker patterns.
- [Amplication documentation](https://docs.amplication.com/guides/getting-started) for deeper guidance on generated NestJS modules, plugins, and recommended workflows.