docs: Update AGENTS.md #19
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,106 @@ | ||
| # AGENTS Guide for `amplication/sample-app` | ||
|
|
||
| ## 1. Project Overview | ||
| - **Purpose:** Sample commerce + logistics system generated by Amplication, split into two NestJS backends and one React Admin frontend. Services cover order management, warehouse/shipment workflows, and an admin UI. | ||
| - **Technologies:** NestJS 10, React 18 + React Admin 5 running on Vite, Prisma ORM, PostgreSQL/MySQL plugins, Kafka (plus NATS helpers in logistics), Docker/Docker Compose, Jest, ESLint/Prettier. | ||
| - **Monorepo Layout:** Root contains `apps/` and `README.md`. There is **no root `package.json`**; every service is isolated. Always `cd` into the target app before installing dependencies or running scripts. | ||
|
|
||
| ## 2. Repository Structure | ||
| | Path | Description | Key Files & Notes | | ||
| | --- | --- | --- | | ||
| | `/README.md` | High-level summary of the three services and broker topics. | Use it for quick context on plugins (JWT, Kafka, PostgreSQL/MySQL). | | ||
| | `/apps/ecommerce-server/` | Commerce backend (NestJS). | `.env`, `Dockerfile`, `docker-compose*.yml`, `nest-cli.json`, `package.json`, `prisma/schema.prisma`, `scripts/seed.ts`, `src/*`. | | ||
| | `/apps/logistic-server/` | Logistics backend (NestJS) focused on warehouses & shipments. | Same layout as ecommerce plus NATS helpers under `src/nats/`. Uses MySQL and Kafka receive topics. | | ||
| | `/apps/ecommerce-admin/` | Admin UI (React Admin on Vite). | `.env`, `Dockerfile`, `configuration/nginx.conf`, `vite.config.ts`, `public/`, `src/`, `package.json`. README still mentions CRA tooling—trust the package scripts. | | ||
|
|
||
| **Naming conventions:** Directories use kebab-case; React components and Nest modules use PascalCase. Configuration stays near service roots (`nest-cli.json`, `tsconfig*.json`, `vite.config.ts`). Environment variables live in each service’s `.env`. | ||
|
|
||
| ## 3. Development Guidelines | ||
| - **Prerequisites:** Node.js ≥16, npm, and Docker (per backend READMEs). Install these before working with any service. | ||
| - **Environment files:** Each service ships with its own `.env`. Populate DB URLs, Kafka hostnames, JWT secrets, etc. Backend READMEs enumerate defaults such as `DB_URL`, `JWT_SECRET_KEY`, and `BCRYPT_SALT`. The frontend expects `PORT` and `REACT_APP_SERVER_URL`. | ||
| - **Per-app workflows:** Run `npm install`, `npm run prisma:generate`, and subsequent commands **inside the specific `apps/<service>` directory**. | ||
| - **Database bootstrap:** Use Docker (`npm run docker:dev`) to start local PostgreSQL/MySQL instances, then `npm run db:init` to apply migrations and seeds. | ||
| - **Credentials:** Generated services provide `admin` / `admin` credentials for first login. Update these outside of development contexts. | ||
|
|
||
| ## 4. Backend Patterns (NestJS Services) | ||
| - **Module layout:** Feature folders like `apps/ecommerce-server/src/product/` or `apps/logistic-server/src/shipment/` contain controllers, resolvers, DTOs, and services. Shared infrastructure lives under `auth/`, `swagger/`, `providers/`, `validators/`, etc. | ||
| - **Prisma integration:** Schemas sit at `apps/*/prisma/schema.prisma` (PostgreSQL for ecommerce, MySQL for logistics). Run `npm run prisma:generate` after changing schemas, and use `db:migrate-*` scripts for migrations. Utility helpers live in `src/prisma/` and `src/prisma.util.ts`. | ||
| - **Seeding:** `scripts/seed.ts` (plus optional `customSeed.ts`) populate baseline data invoked via `npm run seed` or automatically through `npm run db:init`. | ||
| - **Messaging:** Kafka helpers under `src/kafka/` publish/consume topics listed in `README.md`. Logistics also ships `src/nats/` for optional NATS transport wiring. | ||
| - **Testing:** Jest is wired via `ts-jest` (`npm run test`). Spec samples live in `src/prisma.util.spec.ts` and `src/tests/` directories. | ||
| - **Docker workflows:** `docker-compose.dev.yml` spins up DBs and optional brokers; `docker:dev` script wraps it. `compose:up` / `compose:down` manage app containers. `package:container` builds service images. | ||
|
|
||
| ## 5. Frontend Patterns (React Admin + Vite) | ||
| - **Tooling:** Though the README references Create React App (and `npm run eject`), the current tooling is Vite (`vite.config.ts`, `scripts.start = "vite"`). Prefer `npm run start`, `npm run build`, and `npm run serve` for preview. | ||
| - **Structure:** `src/` holds resource folders (`order/`, `product/`, `pages/`), shared providers under `api/` and `data-provider/`, auth wiring in `auth-provider/`, and theming in `theme/`. Static assets live in `public/`; `configuration/nginx.conf` supports containerized hosting. | ||
| - **Environment variables:** `.env` defines `REACT_APP_SERVER_URL` to point at whichever backend URL is active (default `http://localhost:<server-port>`). Update this before running `npm run start`. | ||
| - **Linting & formatting:** Use `npm run lint`, `npm run type-check`, and `npm run format` before committing UI changes. | ||
|
|
||
| ## 6. Common Tasks & Commands | ||
| ### Backends (`apps/ecommerce-server` and `apps/logistic-server` share the same scripts) | ||
| | Intent | Command | | ||
| | --- | --- | | ||
| | Install dependencies | `npm install` | | ||
| | Generate Prisma client | `npm run prisma:generate` | | ||
| | Save new migration | `npm run db:migrate-save -- --name "<description>"` | | ||
| | Apply migrations | `npm run db:migrate-up` | | ||
| | Reset database | `npm run db:clean` | | ||
| | Initialize DB (migrate + seed) | `npm run db:init` | | ||
| | Run seed only | `npm run seed` | | ||
| | Start dev database containers | `npm run docker:dev` | | ||
| | Start HTTP server (prod) | `npm run start` | | ||
| | Start with watch mode | `npm run start:watch` | | ||
| | Start with debugger | `npm run start:debug` | | ||
| | Run tests | `npm run test` | | ||
| | Build distributable | `npm run build` | | ||
| | Compose stack up / down | `npm run compose:up` / `npm run compose:down` | | ||
|
Author
There was a problem hiding this comment. [MAJOR]: The backend command table (line 56) treats Suggested fix: Either update the guide to warn that |
||
| | Build container image | `npm run package:container` | | ||
|
|
||
| **Bootstrap from scratch (backend):** | ||
| 1. `cd apps/<backend>` | ||
| 2. `npm install` | ||
| 3. `cp .env.example .env` (if needed) and adjust DB/Kafka/JWT secrets. | ||
| 4. `npm run prisma:generate` | ||
| 5. `npm run docker:dev` (starts PostgreSQL/MySQL) | ||
| 6. `npm run db:init` | ||
| 7. `npm run start` (or `start:watch` during development) | ||
|
|
||
| ### Frontend (`apps/ecommerce-admin`) | ||
| | Intent | Command | | ||
| | --- | --- | | ||
| | Install dependencies | `npm install` | | ||
| | Start dev server (Vite) | `npm run start` (defaults to port 3001) | | ||
|
Author
There was a problem hiding this comment. [MINOR]: The frontend command table (line 72) claims Suggested fix: Either correct the guide to state the real default port (5173) or add |
||
| | Build production bundle | `npm run build` | | ||
| | Preview built bundle | `npm run serve` | | ||
| | Type-check | `npm run type-check` | | ||
| | Lint & auto-fix | `npm run lint` | | ||
| | Format source | `npm run format` | | ||
| | Build container image | `npm run package:container` | | ||
|
|
||
| **Bootstrap from scratch (frontend):** | ||
| 1. `cd apps/ecommerce-admin` | ||
| 2. Ensure backend URL is reachable, then set `REACT_APP_SERVER_URL` in `.env`. | ||
| 3. `npm install` | ||
| 4. `npm run start` | ||
|
|
||
| ## 7. Quality & Validation | ||
| - **Testing:** Run backend Jest suites with `npm run test`. For UI, rely on `npm run type-check` and `npm run lint` + `npm run format` before publishing changes. | ||
| - **Prisma safety:** Any schema change requires `npm run prisma:generate` and either `db:migrate-save` (dev) or `db:migrate-up` (deploy). `db:clean` wipes data—use carefully. | ||
| - **Security considerations:** Default `admin` / `admin` exists in both backends and exposed in the frontend README. Rotate credentials and secrets before production. Keep JWT secrets, DB passwords, and Kafka configs out of source control by storing them only in `.env` or vaults. | ||
| - **Consistency checks:** Swagger docs (`src/swagger/`) and `grants.json` (RBAC) should be updated when adding resources. Messaging topics listed in `/README.md` must stay in sync with Kafka publishers/consumers under `src/kafka/`. | ||
|
|
||
| ## 8. Reference Examples | ||
| - **Simple UI resource:** `apps/ecommerce-admin/src/pages/` (straightforward React Admin resource declarations and routing). | ||
| - **Complex backend module:** `apps/logistic-server/src/shipment/` demonstrates multi-entity relations and messaging hooks; `apps/logistic-server/src/warehouse/` ties into Prisma models defined in `prisma/schema.prisma`. | ||
| - **Data schema:** `apps/logistic-server/prisma/schema.prisma` (MySQL) vs. `apps/ecommerce-server/prisma/schema.prisma` (PostgreSQL) illustrate provider configuration. | ||
| - **Infrastructure helpers:** `apps/logistic-server/docker-compose.dev.yml` and `apps/ecommerce-server/docker-compose.dev.yml` define DB containers; `apps/ecommerce-admin/configuration/nginx.conf` shows how the UI is served inside containers. | ||
| - **Cross-cutting utilities:** `apps/ecommerce-server/src/auth/`, `src/validators/`, and `src/providers/` illustrate reusable NestJS patterns also mirrored in logistics. | ||
|
|
||
| ## 9. Additional Tips & Resources | ||
| - Each service README (`apps/<service>/README.md`) details environment variables, scripts, and Docker usage—consult them before editing automation. | ||
| - When in doubt about messaging or auth, inspect `apps/*/src/kafka/`, `src/auth/`, and `src/swagger/` for current wiring. | ||
| - For containerized workflows, pair the Dockerfiles with their respective compose files (`docker-compose.dev.yml` for local DBs, `docker-compose.yml` for full stack). | ||
| - Use the root README’s broker topic list to keep Kafka producers/consumers aligned when introducing new entities. | ||
| - Remember that CRA-specific commands (`npm run eject`) in the admin README are legacy; Vite commands in `package.json` are authoritative. | ||
|
|
||
| With this guide and the per-service READMEs, future agents can confidently modify, test, and deploy each part of the monorepo without stepping on neighboring services. | ||
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.
[MAJOR]: Section 3 line 20 and Section 5 line 36 instruct contributors to set
REACT_APP_SERVER_URL, but the Vite admin actually consumesimport.meta.env.VITE_REACT_APP_SERVER_URL(seeapps/ecommerce-admin/src/data-provider/graphqlDataProvider.tsL6-L8 and.envL1-L2). Following the guide leaves the GraphQL client pointing toundefined/graphql, so the UI cannot talk to the backend when onboarding new agents.Suggested fix: Update every frontend environment reference to
VITE_REACT_APP_SERVER_URL(and explain that both the login shortcuts and the GraphQL data provider rely on that name) so the documented setup matches the actual env file and build tooling.