amplication · overcut-ai · Jan 9, 2026 · overcut-ai · Jan 9, 2026 · overcut-ai
diff --git a/AGENTS.md 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/
+    │       ├── <domain>/ (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/<domain>` 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 `<Resource>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 "<descriptive-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)