docs: Update AGENTS.md #16
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,128 @@ | ||
| # AGENTS Guide | ||
|
|
||
| ## Project Overview | ||
| - **Purpose:** Sample Amplication monorepo showcasing full-stack ecommerce + logistics workflows. | ||
| - **Services:** | ||
| - `apps/ecommerce-server`: NestJS backend using PostgreSQL, Kafka "send" pattern, JWT auth via Passport. | ||
| - `apps/ecommerce-admin`: React + React Admin client built with Vite. | ||
| - `apps/logistic-server`: NestJS backend using MySQL, Kafka "receive" pattern with NATS bridge, HTTP Basic auth. | ||
| - **Core stack:** TypeScript, NestJS, React, React Admin, Prisma, Kafka, Docker, Jest. | ||
|
|
||
| | Service | Database | Messaging | Auth | Highlights | | ||
| | --- | --- | --- | --- | --- | | ||
| | ecommerce-server | PostgreSQL via Prisma | Kafka (producer) | JWT / Passport | Generated CRUD modules, send events downstream | | ||
| | ecommerce-admin | N/A (GraphQL client) | N/A | JWT client auth | React Admin resources per entity | | ||
| | logistic-server | MySQL via Prisma | Kafka (consumer) + NATS | HTTP Basic | Receives ecommerce events, bridges to logistics systems | | ||
|
|
||
| ## Repository Structure | ||
| ``` | ||
| apps/ | ||
| ecommerce-server/ | ||
| prisma/ # schema.prisma, migrations, seed scripts | ||
| src/ | ||
| <entity>/ | ||
| base/ # generated DTOs/services/resolvers (do NOT edit) | ||
| <custom>.ts # extend the base classes | ||
| ecommerce-admin/ | ||
| src/ | ||
| <entity>/ # React Admin CRUD screens | ||
| data-provider/ # GraphQL data provider + client config | ||
| auth-provider/ # Auth hooks for React Admin | ||
| logistic-server/ # mirrors ecommerce-server conventions | ||
| README.md # high-level monorepo overview | ||
| ``` | ||
| - **Naming conventions:** | ||
| - Backend entities follow `module/service/resolver` pattern; generated files live in `src/<entity>/base` and must not be modified directly. | ||
| - Frontend components follow `<Entity><Create|Edit|List|Show|Title>.tsx`. | ||
| - Config files use kebab-case; TypeScript files use PascalCase for classes/components. | ||
|
|
||
| ## Development Guidelines & Workflows | ||
| ### Environment & Configuration | ||
| - Each service ships `.env`, `Dockerfile`, `docker-compose.yml`, and `docker-compose.dev.yml` for local infra. | ||
| - Populate `.env` from the corresponding README tables; avoid committing secrets. | ||
| - Use `npm install` inside each service directory (no workspace-level install). | ||
|
|
||
| ### Per-Service Scripts | ||
| | Directory | Script | Purpose | | ||
| | --- | --- | --- | | ||
| | `apps/ecommerce-server` & `apps/logistic-server` | `npm run prisma:generate` | Generate Prisma client + DTO scaffolding | | ||
| | | `npm run docker:dev` | Launch backing services via Docker Compose | | ||
| | | `npm run db:init` | Apply Prisma migrations + seed data | | ||
| | | `npm run start` | Start NestJS server (watch mode) | | ||
| | | `npm run compose:up` | Bring up service container set | | ||
| | | `npm run test` | Execute Jest suite | | ||
| | `apps/ecommerce-admin` | `npm run start` | Start Vite dev server | | ||
| | | `npm run build` | Production build | | ||
| | | `npm run type-check` | Run `tsc --noEmit` | | ||
| | | `npm run lint` / `npm run format` | ESLint + Prettier | | ||
| | | `npm run package:container` | Build container image | | ||
|
|
||
| ### Workflow Notes | ||
| - Backend changes typically require `prisma:generate` after editing `prisma/schema.prisma`. | ||
| - Prefer Docker (`docker:dev`, `compose:up`) for reproducible infra when running Kafka/Postgres/MySQL. | ||
| - React Admin relies on the GraphQL API exposed by ecommerce-server; ensure backend is running before testing UI. | ||
|
|
||
| ## Code Patterns & Best Practices | ||
| - **Generated base classes:** Extend services/resolvers/controllers via the non-base files; regenerate via Prisma to keep DTOs aligned. Never edit `*.base.ts`. | ||
| - **Backend layering:** Modules import shared helpers under `src/kafka`, `src/providers`, `src/auth`, etc. Place custom guards/interceptors there. | ||
| - **Frontend CRUD:** Each resource implements all CRUD screens; leverage shared hooks from `src/data-provider` and `src/auth-provider`. | ||
| - **Messaging:** Use provided Kafka helpers (send pattern in ecommerce, receive pattern + NATS bridge in logistic). Update topic names in service-specific config files. | ||
| - **Authentication:** | ||
| - Ecommerce server uses JWT + Passport; update strategies in `src/auth`. | ||
| - Logistic server enforces HTTP Basic; credentials sourced from `.env`. | ||
| - **Testing:** Jest is configured per service (`apps/*/jest.config.ts`). Add specs under `src/tests/` or alongside modules ending with `.spec.ts`. | ||
|
Author
There was a problem hiding this comment. [minor]: The Testing section states that Jest is configured per service via |
||
| - **Formatting/Linting:** Respect Prettier + ESLint configs shipped per service. | ||
|
|
||
| ## Common Tasks | ||
| ### Run ecommerce-server locally | ||
| ```bash | ||
| cd apps/ecommerce-server | ||
| cp .env.example .env # customize secrets | ||
|
Author
There was a problem hiding this comment. [major]: The "Run ecommerce-server locally" instructions tell agents to copy |
||
| npm install | ||
| npm run docker:dev # start Postgres + Kafka | ||
| npm run prisma:generate | ||
| npm run db:init | ||
| npm run start | ||
| ``` | ||
|
|
||
| ### Generate Prisma client after schema updates | ||
| ```bash | ||
| cd apps/<service>-server | ||
| npm run prisma:generate | ||
| npm run db:init | ||
| ``` | ||
|
|
||
| ### Start the admin client | ||
| ```bash | ||
| cd apps/ecommerce-admin | ||
| npm install | ||
| npm run start | ||
| ``` | ||
|
|
||
| ### Run tests (example: logistic-server) | ||
| ```bash | ||
| cd apps/logistic-server | ||
| npm test | ||
| ``` | ||
|
|
||
| ## Reference Examples | ||
| | Scenario | File/Folder | | ||
| | --- | --- | | ||
| | Simple backend module | `apps/ecommerce-server/src/address/` | | ||
| | Complex backend module | `apps/ecommerce-server/src/order/` | | ||
| | Frontend resource pattern | `apps/ecommerce-admin/src/customer/` | | ||
| | Shared frontend utilities | `apps/ecommerce-admin/src/data-provider/` and `apps/ecommerce-admin/src/auth-provider/` | | ||
| | Infra & schema configuration | `apps/ecommerce-server/prisma/schema.prisma`, `apps/logistic-server/prisma/schema.prisma`, `apps/*/docker-compose.dev.yml` | | ||
|
|
||
| ## Critical Rules & Tips | ||
| - **Do not edit generated base files.** Extend them in sibling files and rerun generators when Prisma schema changes. | ||
| - **Keep env files out of version control.** Use `.env.example` as the authoritative template. | ||
| - **Follow README patterns.** Any new module or service should carry the same sections (Intro, Config, Scripts). | ||
| - **Respect messaging contracts.** Topic names, payload DTOs, and NATS subjects are shared assumptions between services. | ||
| - **Document new scripts.** Update service README tables when adding npm scripts or env vars. | ||
|
|
||
| ## Additional Resources | ||
| - [Ecommerce Server README](apps/ecommerce-server/README.md) | ||
| - [Ecommerce Admin README](apps/ecommerce-admin/README.md) | ||
| - [Logistic Server README](apps/logistic-server/README.md) | ||
| - Amplication Docs: <https://docs.amplication.com> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[minor]: The Environment section claims every service ships
.env,Dockerfile,docker-compose.yml, anddocker-compose.dev.yml, but the frontend atapps/ecommerce-adminonly has.envand aDockerfile, so contributors are told to rely on compose manifests that do not exist. Suggested fix: scope the statement to the backend services or add the missing compose files for the admin client.