diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5b4bb2b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,151 @@ +# AGENTS Guide for amplication/sample-app + +## 📋 Project Overview +- **amplication/sample-app** is a multi-service TypeScript monorepo generated by [Amplication](https://amplication.com) to demonstrate an ecommerce workflow that spans storefront operations and logistics. +- It contains three production-ready services: + - **`apps/ecommerce-server`** – NestJS 10 backend for order and product management, backed by Prisma 5 + PostgreSQL, JWT auth, and KafkaJS messaging topics (`order.*`, `product.*`). + - **`apps/logistic-server`** – NestJS 10 backend for warehouse/shipment flows using Prisma 5 + MySQL, HTTP Basic auth, Kafka receive patterns, and dedicated NATS integration under `src/nats/` for microservice communication. + - **`apps/ecommerce-admin`** – React 18 + React Admin 5 dashboard bootstrapped by Vite, Sass, Apollo Client/GraphQL, plus custom auth/data providers for talking to the servers. +- Cross-cutting technologies: TypeScript everywhere, Prisma ORM, KafkaJS, NATS, Docker/Docker Compose, Jest + ts-node for testing/utilities. Every service exposes `.env` driven configuration tables in its README and consistent npm scripts for dev, database prep, and container workflows. + +## 🗂 Repository Structure +``` +sample-app/ +├── README.md # High-level description of the three services +├── AGENTS.md # This guide +└── apps/ + ├── ecommerce-admin/ # React Admin dashboard (Vite, Sass) + │ ├── .env, Dockerfile, vite.config.ts + │ └── src/ + │ ├── address/, customer/, order/, product/, user/ # CRUD resource folders (Create/Edit/List/Show/Title) + │ ├── auth-provider/, data-provider/ # Authentication + GraphQL data adapters + │ ├── api/, util/, types.ts # Shared helpers mirroring backend filter types + │ └── pages/, Components/, theme/ # Layout and UI chrome + ├── ecommerce-server/ # NestJS + Prisma backend (PostgreSQL, KafkaJS) + │ ├── .env, Dockerfile, docker-compose*.yml, scripts/ + │ └── src/ + │ ├── / (address, customer, order, product, user) with `base/` generated DTOs + resolver/service pairs + │ ├── prisma/, decorators/, providers/, validators/, util/ + │ ├── kafka/, connectMicroservices.ts # Broker client configuration + │ └── prisma.util.ts + prisma.util.spec.ts # Shared DB helper + colocated Jest spec + └── logistic-server/ # NestJS + Prisma backend (MySQL, Kafka receive + NATS) + ├── .env, Dockerfile, docker-compose*.yml, scripts/ + └── src/ + ├── shipment/, warehouse/, user/, auth/ with matching `base/` layers + ├── prisma/, kafka/, nats/, providers/, validators/ + └── tests/, swagger/ # Auto-generated OpenAPI setup +``` +**Naming conventions:** React/Nest components, modules, and services use `PascalCase`, while configuration artifacts (`docker-compose.dev.yml`, `.env`, `vite.config.ts`) stay in kebab/flat case. Domain folders mirror entity names, keeping generated `base/` directories untouched when extending features. + +## ⚙️ Development Guidelines +- **Environment setup:** Follow each service README to copy `.env` files and adjust ports, database URLs, and JWT secrets. Admin UI expects `PORT` (default `3001`) and `REACT_APP_SERVER_URL`; servers require DB credentials, `BCRYPT_SALT`, and JWT settings. +- **Prerequisites:** Ensure Node.js ≥16, npm, and Docker are installed before running scripts. Kafka/MySQL/PostgreSQL containers are provisioned via the provided `docker-compose` files. +- **Scripts:** Every service documents the standard flow—`npm install`, `npm run prisma:generate` (servers), `npm run docker:dev`, `npm run db:init`, and `npm run start`. Containerized runs use `npm run compose:up` / `compose:down`. +- **Configuration hygiene:** Keep README env tables and `.env` defaults aligned. When adding integrations (plugins, brokers), document new variables in the same tabular style. +- **Feature expansion:** + - **Backend:** add a new NestJS module under `src/` with module/service/resolver files plus a `base/` folder generated by Amplication. Reuse `prisma.util.ts` for DB access and expose Kafka/NATS producers/consumers via the existing `kafka/` or `nats/` helpers. + - **Frontend:** mirror backend entities by creating a resource folder (e.g., `src/inventory/`) containing `Create/Edit/List/Show/Title` views and updating `App.tsx` routing plus `auth-provider` / `data-provider` filter definitions. + +## 🧱 Code Patterns +**Backend (NestJS + Prisma)** +- Modular layering per entity: `*.module.ts` wires up providers, `*.service.ts` extends the generated `*.service.base.ts`, and `*.resolver.ts` composes GraphQL endpoints from the corresponding base resolver. +- `base/` directories (for example `apps/ecommerce-server/src/order/base/`) house Amplication-generated DTOs (`OrderWhereInput`, `OrderCreateInput`, etc.) and should remain source-of-truth for typings. +- `prisma/` folder contains the Prisma schema and client bootstrap; `prisma.util.ts` centralizes transaction helpers with Jest coverage in `prisma.util.spec.ts`. +- Integration folders (`kafka/`, `nats/`) configure microservice adapters referenced by `connectMicroservices.ts`; Kafka topics follow the `order.*` / `product.*` naming from the root README. +- Shared infrastructure (decorators, interceptors, providers, validators) lives under dedicated folders and is reused across services to enforce auth, logging, and validation. + +**Frontend (React Admin + Vite)** +- Each resource folder (`src/address/`, `src/order/`, etc.) exports React Admin CRUD screens plus a `Title` helper to keep list/detail titles consistent. +- `auth-provider/` implements login/logout/token refresh while `data-provider/` wraps `ra-data-graphql-amplication` for GraphQL calls typed via `src/types.ts`. +- `src/util/` mirrors backend filter DTOs so list pages can build GraphQL query arguments without re-defining shapes. +- Styling lives in `App.scss`, `theme/`, and resource-specific Sass modules; Vite handles bundling with `vite.config.ts`. +- Testing hooks follow the CRA-to-Vite migration defaults (`setupTests.ts`, React Testing Library) while lint/format scripts enforce Prettier + ESLint baselines. + +## ✅ Quality Standards +- Keep documentation synchronized: whenever scripts/env vars change, update the root README and service READMEs so agents inherit accurate instructions. +- TypeScript must compile cleanly; run `npm run type-check` (admin) or `npm run build` (servers) before delivering changes. +- Run Jest suites (`npm test`) for NestJS utilities plus any added specs; colocate new tests with their subjects. +- Validate environment variables at boot (config modules already enforce this); add schema validation for new variables to prevent runtime surprises. +- Database schema migrations must use Prisma CLI (`db:migrate-save`, `db:migrate-up`) and be committed with corresponding seed updates to keep environments reproducible. +- Docker artifacts (`docker-compose.dev.yml`, `Dockerfile`) must stay in sync with npm scripts so CI/CD and local dev behave the same. + +## ⚠️ Critical Rules +- **Never commit secrets or real connection strings.** Use `.env` and rely on the guidance about secrets managers in each README. +- **Respect Amplication scaffolding.** Generated `base/` files should not be edited manually; extend functionality in the non-base counterparts. +- **Synchronize surfaces.** When adding or renaming entities, update both backends **and** the admin UI resource folders so CRUD coverage stays parity. +- **Broker diligence.** Any change to Kafka producers/consumers or the NATS client must verify topic names (`order.create.v1`, `product.update.v1`, etc.) and payload contracts across services. +- **Database coordination.** Apply migrations and seeds in both ecommerce-server and logistic-server when schemas diverge to avoid runtime drift. + +## 🔧 Common Tasks +### Running ecommerce-admin locally +1. Configure `.env` with the correct `REACT_APP_SERVER_URL`. +2. Install dependencies and start Vite: + ```sh + cd apps/ecommerce-admin + npm install + npm run start + ``` + The dashboard serves at `http://localhost:3001` by default (admin/admin user). + +### Running ecommerce-server for local development +1. Set `.env` with PostgreSQL + JWT settings. +2. Install deps and generate Prisma client: + ```sh + cd apps/ecommerce-server + npm install + npm run prisma:generate + ``` +3. Bring up Postgres + Kafka, initialize the DB, then start Nest: + ```sh + npm run docker:dev + npm run db:init + npm run start + ``` + +### Running logistic-server +Follow the same flow as ecommerce-server (MySQL instead of Postgres): +```sh +cd apps/logistic-server +npm install +npm run prisma:generate +npm run docker:dev +npm run db:init +npm run start +``` +This service listens to Kafka `receive` topics and exposes additional NATS handlers configured under `src/nats/`. + +### Generating Prisma migrations & seeding data +```sh +# Inside either server directory +npm run db:migrate-save -- --name "" +npm run db:migrate-up +npm run seed +``` +Use `npm run db:clean` to reset during development; `db:init` already chains migrate + seed for a fresh environment. + +### Running Docker Compose services +- Spin up the backend containers with `npm run compose:up` and tear them down via `npm run compose:down -- --volumes` if you need a clean slate. +- Use `npm run package:container` when publishing updated images. + +### Extending React Admin resources +1. Duplicate the pattern from `apps/ecommerce-admin/src/address/` to a new folder. +2. Implement `Create/Edit/List/Show/Title` components using the shared `util/` filters and register the resource in `App.tsx`. +3. Update `data-provider` types if new fields/filters are introduced. + +### Adding a NestJS domain module +1. Copy the structure from `apps/ecommerce-server/src/order/` (module/service/resolver + `base/`). +2. Regenerate base files through Amplication or by extending existing DTOs. +3. Wire the new module into `app.module.ts`, expose necessary Kafka/NATS patterns, and sync React Admin resources if the entity is user-facing. + +## 📂 Reference Examples +- `apps/ecommerce-admin/src/pages/Dashboard.tsx` – minimal dashboard component showing how global widgets are wired into React Admin routing. +- `apps/ecommerce-admin/src/address/` – canonical CRUD resource folder demonstrating component naming and usage of shared providers. +- `apps/ecommerce-server/src/order/` – full NestJS module with generated base DTOs, resolver, and service that illustrates backend layering. +- `apps/logistic-server/src/nats/` – microservice integration scaffolding for NATS subjects, reflecting how non-HTTP brokers fit into the project. + +## 🔗 Additional Resources +- [Root README](./README.md) +- [ecommerce-admin README](./apps/ecommerce-admin/README.md) +- [ecommerce-server README](./apps/ecommerce-server/README.md) +- [logistic-server README](./apps/logistic-server/README.md) +- [Amplication Documentation](https://docs.amplication.com/guides/getting-started)