From 7a15bb87ba90f1060778fe5fa9095dd593a4f260 Mon Sep 17 00:00:00 2001 From: overcut Date: Sat, 10 Jan 2026 00:24:25 +0000 Subject: [PATCH 1/7] docs: update AGENTS.md - Document service layout, tooling, and workflows - Capture messaging, testing, and security guidance --- AGENTS.md | 195 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 195 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1c8a733 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,195 @@ +# AGENTS Guide for `amplication/sample-app` + +## ๐Ÿ“ฆ Project Overview +- Amplication-generated monorepo housing three independent services under `apps/`: two NestJS backends (`ecommerce-server`, `logistic-server`) and a React Admin frontend (`ecommerce-admin`). +- Shared patterns: Prisma for data access, Kafka for messaging, `.env`-driven configuration, and service-specific `package.json`, `Dockerfile`, and `docker-compose` files. There is **no root-level `package.json`**โ€”each service manages its own dependencies. +- Technology stack highlights: + - **ecommerce-server:** NestJS + PostgreSQL + JWT + Kafka producer topics for order & product lifecycle. + - **logistic-server:** NestJS + MySQL + HTTP Basic Auth + Kafka consumers + dedicated NATS integration for logistics workflows. + - **ecommerce-admin:** React Admin on Vite, consuming the ecommerce API via `REACT_APP_SERVER_URL`. + +## ๐Ÿ—‚๏ธ Repository Layout +- Root contains only `README.md` plus the `apps/` directory; all tooling, Prisma schemas, and scripts live within each service folder. +- Each backend service exposes a consistent structure: `Dockerfile`, `docker-compose*.yml`, `.env`, `package.json`, `prisma/schema.prisma`, `scripts/seed.ts`, and `src/` modules (auth, domain resources like `order/`, messaging folders like `kafka/` or `nats/`, and `tests/`). +- The admin app includes Vite config (`vite.config.ts`), `src/` resources (e.g., `order/`, `product/`, `pages/Dashboard.tsx`), and utility folders (`auth-provider/`, `data-provider/`, `theme/`). + +``` +. +โ”œโ”€โ”€ README.md +โ””โ”€โ”€ apps/ + โ”œโ”€โ”€ ecommerce-server/ + โ”‚ โ”œโ”€โ”€ README.md, package.json, Dockerfile, docker-compose*.yml + โ”‚ โ”œโ”€โ”€ prisma/schema.prisma & scripts/seed.ts + โ”‚ โ””โ”€โ”€ src/(order/, product/, auth/, kafka/, tests/, ...) + โ”œโ”€โ”€ logistic-server/ + โ”‚ โ”œโ”€โ”€ README.md, package.json, Dockerfile, docker-compose*.yml + โ”‚ โ”œโ”€โ”€ prisma/schema.prisma & scripts/seed.ts + โ”‚ โ””โ”€โ”€ src/(shipment/, warehouse/, auth/, kafka/, nats/, tests/, ...) + โ””โ”€โ”€ ecommerce-admin/ + โ”œโ”€โ”€ README.md, package.json, Dockerfile + โ””โ”€โ”€ src/(address/, order/, pages/Dashboard.tsx, api/, auth-provider/, ...) +``` + +## ๐Ÿงฉ Service Profiles +### ๐Ÿงฎ ecommerce-server (`apps/ecommerce-server`) +- **Role:** Order & product management API with JWT auth, PostgreSQL persistence, and Kafka producer integrations (`src/kafka/`). +- **Core stack:** NestJS, Prisma, PostgreSQL, KafkaJS, Swagger, Jest. +- **Local infra:** `docker-compose.dev.yml` launches PostgreSQL plus Kafka+Zookeeper+kafka-ui; `npm run docker:dev` wraps it. +- **Credentials:** Default `admin` / `admin` account for dev/testing (documented in `apps/ecommerce-server/README.md`). + +| Name | Description | Default / Notes | Source | +| --- | --- | --- | --- | +| `BCRYPT_SALT` | Salt used for hashing | `[random-string]` | `apps/ecommerce-server/README.md` | +| `COMPOSE_PROJECT_NAME` | Compose stack prefix | `amp_[service-identifier]` | same | +| `PORT` | HTTP port | `3000` | same | +| `DB_URL` | Prisma connection URL | `[provider]://[user]:[password]@localhost:[port]/[db]` | same | +| `DB_PORT` | Database host port | provider-specific (`5432` default) | same | +| `DB_USER` | Database user | `[username]` | same | +| `DB_PASSWORD` | Database password | `[password]` | same | +| `DB_NAME` | Database name | `[service-name]` | same | +| `JWT_SECRET_KEY` | JWT signing secret | `[secret]` | same | +| `JWT_EXPIRATION` | JWT TTL | `2d` | same | + +### ๐Ÿšš logistic-server (`apps/logistic-server`) +- **Role:** Warehouse & shipment service secured with HTTP Basic auth, using MySQL storage, Kafka consumers, and NATS-based logistics messaging (`src/nats/`). +- **Core stack:** NestJS, Prisma, MySQL, KafkaJS, `nats` client, Swagger, Jest. +- **Local infra:** `docker-compose.dev.yml` provisions MySQL, Adminer, Kafka stack, kafka-ui, and an explicit `nats` container. +- **Credentials:** Shares the generated `admin` / `admin` dev credentials; adjust Basic Auth secrets before production. + +| Name | Description | Default / Notes | Source | +| --- | --- | --- | --- | +| `BCRYPT_SALT` | Salt used for hashing | `[random-string]` | `apps/logistic-server/README.md` | +| `COMPOSE_PROJECT_NAME` | Compose stack prefix | `amp_[service-identifier]` | same | +| `PORT` | HTTP port | `3000` | same | +| `DB_URL` | Prisma connection URL | `[provider]://[user]:[password]@localhost:[port]/[db]` | same | +| `DB_PORT` | Database host port | provider-specific (`3306` default) | same | +| `DB_USER` | Database user | `[username]` | same | +| `DB_PASSWORD` | Database password | `[password]` | same | +| `DB_NAME` | Database name | `[service-name]` | same | +| `JWT_SECRET_KEY` | Token secret (used by guards) | `[secret]` | same | +| `JWT_EXPIRATION` | Token TTL | `2d` | same | + +### ๐Ÿ–ฅ๏ธ ecommerce-admin (`apps/ecommerce-admin`) +- **Role:** React Admin dashboard consuming the ecommerce GraphQL API; uses Vite for dev/build and React Admin resources under `src//`. +- **Core stack:** React 18, React Admin 5, Apollo Client, Vite, TypeScript, ESLint, Prettier, Sass. +- **Local infra:** Expects the ecommerce server running; `REACT_APP_SERVER_URL` must point to that host/port. + +| Name | Description | Default / Notes | Source | +| --- | --- | --- | --- | +| `PORT` | Frontend dev server port | `3001` | `apps/ecommerce-admin/README.md` | +| `REACT_APP_SERVER_URL` | Base URL for backend API | `http://localhost:[server-port]` | same | + +## ๐Ÿ› ๏ธ Tooling & Scripts +### Backend services (`apps/ecommerce-server`, `apps/logistic-server`) +| Script | Purpose | File | +| --- | --- | --- | +| `npm run start` / `start:watch` / `start:debug` | Run NestJS server (optionally watch/debug). | `apps/*-server/package.json` | +| `npm run build` | Compile via Nest CLI. | same | +| `npm run test` | Execute Jest test suite (`ts-jest` preset). | same | +| `npm run prisma:generate` | Generate Prisma client from `prisma/schema.prisma`. | same | +| `npm run db:migrate-save` | Create a new Prisma migration (dev). | same | +| `npm run db:migrate-up` | Apply migrations (deploy). | same | +| `npm run db:clean` | Reset database via Prisma. | same | +| `npm run db:init` | Runs `db:migrate-save`, `db:migrate-up`, then `seed`. | same | +| `npm run seed` | Execute `scripts/seed.ts` (can be customized via `scripts/customSeed.ts`). | same | +| `npm run docker:dev` | Start service-specific infra from `docker-compose.dev.yml`. | same | +| `npm run compose:up` / `compose:down` | Run/tear down Dockerized app stack. | same | +| `npm run package:container` | Build service Docker image via `Dockerfile`. | same | + +### Frontend (`apps/ecommerce-admin`) +| Script | Purpose | File | +| --- | --- | --- | +| `npm run start` | Launch Vite dev server on `PORT`. | `apps/ecommerce-admin/package.json` | +| `npm run build` | Production build output under `dist/`. | same | +| `npm run serve` | Preview built assets with Vite preview. | same | +| `npm run type-check` | Run TypeScript compiler without emit. | same | +| `npm run lint` | Lint & auto-fix `src/` via ESLint. | same | +| `npm run format` | Format `src/` via Prettier. | same | +| `npm run package:container` | Build dashboard container image. | same | + +## ๐Ÿš€ Development Workflow +1. **Pick a service directory** (e.g., `cd apps/ecommerce-server`) and copy/adjust the provided `.env` file; never share sensitive overrides. +2. **Install dependencies** with `npm install` inside that service. +3. **Generate Prisma artifacts** via `npm run prisma:generate` (backends only) when schemas change. +4. **Provision local infra** with `npm run docker:dev` to bring up the serviceโ€™s database, Kafka stack, and (for logistics) NATS & Adminer. +5. **Initialize data** using `npm run db:init` to run migrations plus `scripts/seed.ts`. +6. **Start the service** with `npm run start` (servers) or `npm run start` from `apps/ecommerce-admin` after ensuring `REACT_APP_SERVER_URL` points at the running API. +7. **Alternative container path:** `npm run compose:up` builds & runs the service container using the provided `Dockerfile` and compose file. + +## ๐Ÿ”— Messaging & Integrations +- **Kafka topics (from `README.md`):** `order.create.v1`, `order.update.v1`, `product.create.v1`, `product.update.v1`. + - `apps/ecommerce-server` sends messages on those topics (see `src/kafka/kafka.producer.service.ts`). + - `apps/logistic-server` consumes the same topics (`src/kafka/kafka.service.ts`). +- **NATS (logistics):** `apps/logistic-server/docker-compose.dev.yml` defines a `nats` container, and the service implements handlers in `src/nats/` (`nats.module.ts`, `nats.service.ts`, `topics.ts`). Kafka and NATS clients are wired in `src/connectMicroservices.ts`. + +## โœ… Testing & Quality +- **Backends:** Run `npm run test` inside each server to execute Jest suites configured via `ts-jest` (`package.json > jest`). Domain-focused specs live under `apps/ecommerce-server/src/tests/` and `apps/logistic-server/src/tests/` (e.g., `auth/token.service.spec.ts`, `health/health.service.spec.ts`). +- **Frontend:** While no standalone `test` script is declared, quality gates rely on `npm run type-check`, `npm run lint`, `npm run format`, and `npm run build`. The Vite/React Testing Library setup is scaffolded in `src/setupTests.ts` should you add tests. +- **Data prep:** Use `npm run seed` (servers) for deterministic fixtures before running suites; ensure Dockerized databases and brokers are already healthy. + +## โš ๏ธ Critical Rules & Security +- `.env` files in each service contain generated secrets (hash salts, DB passwords, JWT keys); **never commit real credentials**. Follow README guidance to migrate secrets into a secure vault for production deployments. +- Backends require their databases, Kafka, and (for logistics) NATS to be running before executing `npm run start`, `npm run test`, or any migrationsโ€”`docker:dev` is mandatory. +- Default `admin` / `admin` credentials exist purely for local testing; rotate before exposing any environment publicly. +- When editing Prisma schemas or seed scripts, regenerate the Prisma client and re-run migrations to avoid drift. + +## ๐Ÿ“‹ Common Tasks +### Ecommerce-server dev loop +1. `cd apps/ecommerce-server` +2. `npm install` +3. `npm run prisma:generate` +4. `npm run docker:dev` +5. `npm run db:init` +6. `npm run start` + +### Logistic-server consumer stack +1. `cd apps/logistic-server` +2. `npm install` +3. `npm run prisma:generate` +4. `npm run docker:dev` (brings up MySQL, Adminer, Kafka, kafka-ui, NATS) +5. `npm run db:init` +6. `npm run start` + +### Ecommerce-admin dashboard +1. `cd apps/ecommerce-admin` +2. Configure `.env` with the active backend URL (`REACT_APP_SERVER_URL=http://localhost:3000` by default) +3. `npm install` +4. `npm run start` (uses Vite on port `3001`) +5. For a production preview: `npm run build && npm run serve` + +### Database migrations & seeds (either backend) +```sh +cd apps/-server +npm run db:migrate-save -- --name "add-new-model" +npm run db:migrate-up +npm run seed +``` + +### Tear down Docker resources +```sh +cd apps/-server +npm run compose:down +# or stop only dev infra +docker-compose -f docker-compose.dev.yml down --volumes +``` + +## ๐Ÿ“š Reference Examples +| Path | Why it matters | +| --- | --- | +| `apps/ecommerce-admin/src/pages/Dashboard.tsx` | Minimal React Admin dashboard pattern with Material UI components. | +| `apps/ecommerce-admin/src/data-provider/graphqlDataProvider.ts` | Apollo-powered data provider wiring for GraphQL resources. | +| `apps/ecommerce-server/src/order/` | Typical NestJS module/resolver/service triple for a domain resource. | +| `apps/ecommerce-server/src/kafka/kafka.producer.service.ts` | Implementation of Kafka producers emitting order/product events. | +| `apps/logistic-server/src/kafka/kafka.service.ts` | Kafka consumer setup for receive-pattern workflows. | +| `apps/logistic-server/src/nats/nats.service.ts` | NATS integration showing subscription handling. | +| `apps/ecommerce-server/src/tests/auth/token.service.spec.ts` | Example Jest spec exercising auth logic. | +| `apps/logistic-server/src/tests/auth/token.service.spec.ts` | Logistics-side auth test mirroring backend conventions. | + +## ๐Ÿ”— Additional Resources +- [Root README](README.md) โ€” high-level summary plus Kafka topic definitions. +- [Amplication documentation](https://docs.amplication.com/guides/getting-started) โ€” covers generated architecture expectations. +- [ecommerce-server README](apps/ecommerce-server/README.md) +- [logistic-server README](apps/logistic-server/README.md) +- [ecommerce-admin README](apps/ecommerce-admin/README.md) +- [ecommerce-server docker-compose.dev.yml](apps/ecommerce-server/docker-compose.dev.yml) +- [logistic-server docker-compose.dev.yml](apps/logistic-server/docker-compose.dev.yml) From 520b759a1bb97af1c8e2608031a869e6600be9ac Mon Sep 17 00:00:00 2001 From: overcut Date: Mon, 12 Jan 2026 00:15:40 +0000 Subject: [PATCH 2/7] docs: update AGENTS.md --- AGENTS.md | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1c8a733..53b4bcc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,10 +3,11 @@ ## ๐Ÿ“ฆ Project Overview - Amplication-generated monorepo housing three independent services under `apps/`: two NestJS backends (`ecommerce-server`, `logistic-server`) and a React Admin frontend (`ecommerce-admin`). - Shared patterns: Prisma for data access, Kafka for messaging, `.env`-driven configuration, and service-specific `package.json`, `Dockerfile`, and `docker-compose` files. There is **no root-level `package.json`**โ€”each service manages its own dependencies. +- **Regeneration safety:** Amplication-generated artifacts live under `src//base/*`; extend or override behavior in sibling files so regenerations never overwrite custom logic. - Technology stack highlights: - **ecommerce-server:** NestJS + PostgreSQL + JWT + Kafka producer topics for order & product lifecycle. - **logistic-server:** NestJS + MySQL + HTTP Basic Auth + Kafka consumers + dedicated NATS integration for logistics workflows. - - **ecommerce-admin:** React Admin on Vite, consuming the ecommerce API via `REACT_APP_SERVER_URL`. + - **ecommerce-admin:** React Admin on Vite, consuming the ecommerce API via `VITE_REACT_APP_SERVER_URL`. ## ๐Ÿ—‚๏ธ Repository Layout - Root contains only `README.md` plus the `apps/` directory; all tooling, Prisma schemas, and scripts live within each service folder. @@ -49,6 +50,10 @@ | `DB_NAME` | Database name | `[service-name]` | same | | `JWT_SECRET_KEY` | JWT signing secret | `[secret]` | same | | `JWT_EXPIRATION` | JWT TTL | `2d` | same | +| `KAFKA_BROKERS` | Comma-separated Kafka bootstrap broker addresses. | `localhost:9092` | same | +| `KAFKA_CLIENT_ID` | Client ID used by ecommerce-server when connecting to Kafka. | `ecommerce-server` | same | +| `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `[group-id]` | same | +| `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | same | ### ๐Ÿšš logistic-server (`apps/logistic-server`) - **Role:** Warehouse & shipment service secured with HTTP Basic auth, using MySQL storage, Kafka consumers, and NATS-based logistics messaging (`src/nats/`). @@ -68,16 +73,21 @@ | `DB_NAME` | Database name | `[service-name]` | same | | `JWT_SECRET_KEY` | Token secret (used by guards) | `[secret]` | same | | `JWT_EXPIRATION` | Token TTL | `2d` | same | +| `KAFKA_BROKERS` | Comma-separated Kafka bootstrap broker addresses. | `localhost:9092` | same | +| `KAFKA_CLIENT_ID` | Client ID used by logistic-server when connecting to Kafka. | `logistic-server` | same | +| `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `[group-id]` | same | +| `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | same | +| `NATS_SERVERS` | Comma-separated NATS server URLs consumed by logistic-server. | `nats://localhost:4222` | same | ### ๐Ÿ–ฅ๏ธ ecommerce-admin (`apps/ecommerce-admin`) - **Role:** React Admin dashboard consuming the ecommerce GraphQL API; uses Vite for dev/build and React Admin resources under `src//`. - **Core stack:** React 18, React Admin 5, Apollo Client, Vite, TypeScript, ESLint, Prettier, Sass. -- **Local infra:** Expects the ecommerce server running; `REACT_APP_SERVER_URL` must point to that host/port. +- **Local infra:** Expects the ecommerce server running; `VITE_REACT_APP_SERVER_URL` must point to that host/port. | Name | Description | Default / Notes | Source | | --- | --- | --- | --- | | `PORT` | Frontend dev server port | `3001` | `apps/ecommerce-admin/README.md` | -| `REACT_APP_SERVER_URL` | Base URL for backend API | `http://localhost:[server-port]` | same | +| `VITE_REACT_APP_SERVER_URL` | Public URL of ecommerce-server consumed by the admin UI. | `http://localhost:[server-port]` | same | ## ๐Ÿ› ๏ธ Tooling & Scripts ### Backend services (`apps/ecommerce-server`, `apps/logistic-server`) @@ -113,7 +123,7 @@ 3. **Generate Prisma artifacts** via `npm run prisma:generate` (backends only) when schemas change. 4. **Provision local infra** with `npm run docker:dev` to bring up the serviceโ€™s database, Kafka stack, and (for logistics) NATS & Adminer. 5. **Initialize data** using `npm run db:init` to run migrations plus `scripts/seed.ts`. -6. **Start the service** with `npm run start` (servers) or `npm run start` from `apps/ecommerce-admin` after ensuring `REACT_APP_SERVER_URL` points at the running API. +6. **Start the service** with `npm run start` (servers) or `npm run start` from `apps/ecommerce-admin` after ensuring `VITE_REACT_APP_SERVER_URL` points at the running API. 7. **Alternative container path:** `npm run compose:up` builds & runs the service container using the provided `Dockerfile` and compose file. ## ๐Ÿ”— Messaging & Integrations @@ -129,6 +139,7 @@ ## โš ๏ธ Critical Rules & Security - `.env` files in each service contain generated secrets (hash salts, DB passwords, JWT keys); **never commit real credentials**. Follow README guidance to migrate secrets into a secure vault for production deployments. +- Never modify files under `src/**/base/`; Amplication regenerates them and any customizations will be overwritten. Extend behavior in sibling modules/services/controllers instead. - Backends require their databases, Kafka, and (for logistics) NATS to be running before executing `npm run start`, `npm run test`, or any migrationsโ€”`docker:dev` is mandatory. - Default `admin` / `admin` credentials exist purely for local testing; rotate before exposing any environment publicly. - When editing Prisma schemas or seed scripts, regenerate the Prisma client and re-run migrations to avoid drift. @@ -152,7 +163,7 @@ ### Ecommerce-admin dashboard 1. `cd apps/ecommerce-admin` -2. Configure `.env` with the active backend URL (`REACT_APP_SERVER_URL=http://localhost:3000` by default) +2. Configure `.env` with the active backend URL (`VITE_REACT_APP_SERVER_URL=http://localhost:3000` by default) 3. `npm install` 4. `npm run start` (uses Vite on port `3001`) 5. For a production preview: `npm run build && npm run serve` @@ -182,6 +193,7 @@ docker-compose -f docker-compose.dev.yml down --volumes | `apps/ecommerce-server/src/kafka/kafka.producer.service.ts` | Implementation of Kafka producers emitting order/product events. | | `apps/logistic-server/src/kafka/kafka.service.ts` | Kafka consumer setup for receive-pattern workflows. | | `apps/logistic-server/src/nats/nats.service.ts` | NATS integration showing subscription handling. | +| `apps/logistic-server/src/warehouse/` | Generated `base/` DTOs plus adjacent custom controllers/services illustrating the layering pattern. | | `apps/ecommerce-server/src/tests/auth/token.service.spec.ts` | Example Jest spec exercising auth logic. | | `apps/logistic-server/src/tests/auth/token.service.spec.ts` | Logistics-side auth test mirroring backend conventions. | From bb81ce96f6177b9eda35e689c68f601c37609912 Mon Sep 17 00:00:00 2001 From: overcut Date: Thu, 15 Jan 2026 00:10:31 +0000 Subject: [PATCH 3/7] docs: update AGENTS.md --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 53b4bcc..2f111f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,9 @@ - **ecommerce-server:** NestJS + PostgreSQL + JWT + Kafka producer topics for order & product lifecycle. - **logistic-server:** NestJS + MySQL + HTTP Basic Auth + Kafka consumers + dedicated NATS integration for logistics workflows. - **ecommerce-admin:** React Admin on Vite, consuming the ecommerce API via `VITE_REACT_APP_SERVER_URL`. +- Toolchain versions (from the app-level `package.json` files): + - Backends run on NestJS `10.2.x`, Prisma `5.4.x`, TypeScript `5.4.x`, KafkaJS `2.2.x`, npm-run-all `4.1.x`, and (logistics) NATS `2.17.x`. + - The admin UI uses React `18.3.x`, React Admin `5.1.x`, Apollo Client `3.6.x`, Vite `4.3.x`, and TypeScript `5.1.x`. ## ๐Ÿ—‚๏ธ Repository Layout - Root contains only `README.md` plus the `apps/` directory; all tooling, Prisma schemas, and scripts live within each service folder. From ad82e147d39c742f57bdd4b743fc431daabc380a Mon Sep 17 00:00:00 2001 From: overcut Date: Fri, 16 Jan 2026 00:11:09 +0000 Subject: [PATCH 4/7] docs: update AGENTS.md --- AGENTS.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2f111f5..6682115 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -76,16 +76,17 @@ | `DB_NAME` | Database name | `[service-name]` | same | | `JWT_SECRET_KEY` | Token secret (used by guards) | `[secret]` | same | | `JWT_EXPIRATION` | Token TTL | `2d` | same | -| `KAFKA_BROKERS` | Comma-separated Kafka bootstrap broker addresses. | `localhost:9092` | same | -| `KAFKA_CLIENT_ID` | Client ID used by logistic-server when connecting to Kafka. | `logistic-server` | same | -| `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `[group-id]` | same | -| `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | same | -| `NATS_SERVERS` | Comma-separated NATS server URLs consumed by logistic-server. | `nats://localhost:4222` | same | +| `KAFKA_BROKERS` | Comma-separated Kafka bootstrap broker addresses. | `localhost:9092` | `apps/logistic-server/.env` | +| `KAFKA_CLIENT_ID` | Client ID used by logistic-server when connecting to Kafka. | `logistic-server` | `apps/logistic-server/.env` | +| `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `logistic` | `apps/logistic-server/.env` | +| `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | `apps/logistic-server/.env` | +| `NATS_SERVERS` | Comma-separated NATS server host:port entries; the NestJS NATS transport prepends `nats://` automatically. | `localhost:4222` | `apps/logistic-server/.env` (mirrors `docker-compose.dev.yml`) | ### ๐Ÿ–ฅ๏ธ ecommerce-admin (`apps/ecommerce-admin`) - **Role:** React Admin dashboard consuming the ecommerce GraphQL API; uses Vite for dev/build and React Admin resources under `src//`. - **Core stack:** React 18, React Admin 5, Apollo Client, Vite, TypeScript, ESLint, Prettier, Sass. - **Local infra:** Expects the ecommerce server running; `VITE_REACT_APP_SERVER_URL` must point to that host/port. +- **Heads-up:** `apps/ecommerce-admin/README.md` still references Create React Appโ€”consult `apps/ecommerce-admin/package.json` and `.env` for the authoritative Vite scripts/envs (including `VITE_REACT_APP_SERVER_URL`). | Name | Description | Default / Notes | Source | | --- | --- | --- | --- | From fc0db1b63d41f1926d2816491cf2c90857aea301 Mon Sep 17 00:00:00 2001 From: overcut Date: Sat, 17 Jan 2026 00:06:07 +0000 Subject: [PATCH 5/7] docs: update AGENTS.md --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 6682115..29ad6a9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -196,10 +196,11 @@ docker-compose -f docker-compose.dev.yml down --volumes | `apps/ecommerce-server/src/order/` | Typical NestJS module/resolver/service triple for a domain resource. | | `apps/ecommerce-server/src/kafka/kafka.producer.service.ts` | Implementation of Kafka producers emitting order/product events. | | `apps/logistic-server/src/kafka/kafka.service.ts` | Kafka consumer setup for receive-pattern workflows. | -| `apps/logistic-server/src/nats/nats.service.ts` | NATS integration showing subscription handling. | +| `apps/logistic-server/src/nats/` | Authoritative NATS wiring (module, topics, microservice bootstrap) for complex logistics messaging. | | `apps/logistic-server/src/warehouse/` | Generated `base/` DTOs plus adjacent custom controllers/services illustrating the layering pattern. | | `apps/ecommerce-server/src/tests/auth/token.service.spec.ts` | Example Jest spec exercising auth logic. | | `apps/logistic-server/src/tests/auth/token.service.spec.ts` | Logistics-side auth test mirroring backend conventions. | +| `apps/logistic-server/docker-compose.dev.yml` | Comprehensive dev infra stack (MySQL, Adminer, Kafka, kafka-ui, NATS) used across backend workflows. | ## ๐Ÿ”— Additional Resources - [Root README](README.md) โ€” high-level summary plus Kafka topic definitions. From 9d93009f22720d1d12d8c9436b492b619598ad49 Mon Sep 17 00:00:00 2001 From: overcut Date: Wed, 21 Jan 2026 00:13:21 +0000 Subject: [PATCH 6/7] docs: update AGENTS.md --- AGENTS.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 29ad6a9..b72d6d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -37,7 +37,7 @@ ## ๐Ÿงฉ Service Profiles ### ๐Ÿงฎ ecommerce-server (`apps/ecommerce-server`) - **Role:** Order & product management API with JWT auth, PostgreSQL persistence, and Kafka producer integrations (`src/kafka/`). -- **Core stack:** NestJS, Prisma, PostgreSQL, KafkaJS, Swagger, Jest. +- **Core stack:** NestJS 10.2.x + Prisma 5.4.x, TypeScript 5.4.x, PostgreSQL, KafkaJS 2.2.x producer, Swagger, Jest. - **Local infra:** `docker-compose.dev.yml` launches PostgreSQL plus Kafka+Zookeeper+kafka-ui; `npm run docker:dev` wraps it. - **Credentials:** Default `admin` / `admin` account for dev/testing (documented in `apps/ecommerce-server/README.md`). @@ -54,13 +54,13 @@ | `JWT_SECRET_KEY` | JWT signing secret | `[secret]` | same | | `JWT_EXPIRATION` | JWT TTL | `2d` | same | | `KAFKA_BROKERS` | Comma-separated Kafka bootstrap broker addresses. | `localhost:9092` | same | -| `KAFKA_CLIENT_ID` | Client ID used by ecommerce-server when connecting to Kafka. | `ecommerce-server` | same | -| `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `[group-id]` | same | +| `KAFKA_CLIENT_ID` | Client ID used by ecommerce-server when connecting to Kafka. | `ecommerce` | same | +| `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `ecommerce` | same | | `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | same | ### ๐Ÿšš logistic-server (`apps/logistic-server`) - **Role:** Warehouse & shipment service secured with HTTP Basic auth, using MySQL storage, Kafka consumers, and NATS-based logistics messaging (`src/nats/`). -- **Core stack:** NestJS, Prisma, MySQL, KafkaJS, `nats` client, Swagger, Jest. +- **Core stack:** NestJS 10.2.x + Prisma 5.4.x, MySQL, KafkaJS 2.2.x consumer, NATS 2.17.x client, Swagger, Jest. - **Local infra:** `docker-compose.dev.yml` provisions MySQL, Adminer, Kafka stack, kafka-ui, and an explicit `nats` container. - **Credentials:** Shares the generated `admin` / `admin` dev credentials; adjust Basic Auth secrets before production. @@ -77,14 +77,15 @@ | `JWT_SECRET_KEY` | Token secret (used by guards) | `[secret]` | same | | `JWT_EXPIRATION` | Token TTL | `2d` | same | | `KAFKA_BROKERS` | Comma-separated Kafka bootstrap broker addresses. | `localhost:9092` | `apps/logistic-server/.env` | -| `KAFKA_CLIENT_ID` | Client ID used by logistic-server when connecting to Kafka. | `logistic-server` | `apps/logistic-server/.env` | +| `KAFKA_CLIENT_ID` | Client ID used by logistic-server when connecting to Kafka. | `logistic` | `apps/logistic-server/.env` | | `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `logistic` | `apps/logistic-server/.env` | | `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | `apps/logistic-server/.env` | -| `NATS_SERVERS` | Comma-separated NATS server host:port entries; the NestJS NATS transport prepends `nats://` automatically. | `localhost:4222` | `apps/logistic-server/.env` (mirrors `docker-compose.dev.yml`) | +| `NATS_SERVERS` | Comma-separated NATS server endpoints. Default `.env` value is `localhost:4222`, but the NATS factory consumes the string as-isโ€”provide fully qualified entries like `nats://host:4222` when not using the compose default. | `localhost:4222` | `apps/logistic-server/.env` (mirrors `docker-compose.dev.yml`) | ### ๐Ÿ–ฅ๏ธ ecommerce-admin (`apps/ecommerce-admin`) - **Role:** React Admin dashboard consuming the ecommerce GraphQL API; uses Vite for dev/build and React Admin resources under `src//`. -- **Core stack:** React 18, React Admin 5, Apollo Client, Vite, TypeScript, ESLint, Prettier, Sass. +- **Core stack:** React, React Admin, Apollo Client, Vite, TypeScript, ESLint, Prettier, Sass. +- **Core stack versions:** React 18.3.x / React Admin 5.1.x / Vite 4.3.x / TypeScript 5.1.x. - **Local infra:** Expects the ecommerce server running; `VITE_REACT_APP_SERVER_URL` must point to that host/port. - **Heads-up:** `apps/ecommerce-admin/README.md` still references Create React Appโ€”consult `apps/ecommerce-admin/package.json` and `.env` for the authoritative Vite scripts/envs (including `VITE_REACT_APP_SERVER_URL`). @@ -104,7 +105,7 @@ | `npm run db:migrate-save` | Create a new Prisma migration (dev). | same | | `npm run db:migrate-up` | Apply migrations (deploy). | same | | `npm run db:clean` | Reset database via Prisma. | same | -| `npm run db:init` | Runs `db:migrate-save`, `db:migrate-up`, then `seed`. | same | +| `npm run db:init` | First-time bootstrap helper chaining `db:migrate-save -- --name "initial version"`, `db:migrate-up`, then `seed`; for later changes run `db:migrate-save -- --name ` followed by `db:migrate-up`. | same | | `npm run seed` | Execute `scripts/seed.ts` (can be customized via `scripts/customSeed.ts`). | same | | `npm run docker:dev` | Start service-specific infra from `docker-compose.dev.yml`. | same | | `npm run compose:up` / `compose:down` | Run/tear down Dockerized app stack. | same | @@ -126,14 +127,14 @@ 2. **Install dependencies** with `npm install` inside that service. 3. **Generate Prisma artifacts** via `npm run prisma:generate` (backends only) when schemas change. 4. **Provision local infra** with `npm run docker:dev` to bring up the serviceโ€™s database, Kafka stack, and (for logistics) NATS & Adminer. -5. **Initialize data** using `npm run db:init` to run migrations plus `scripts/seed.ts`. +5. **Initialize data** using `npm run db:init` only for first-time bootstrap (runs `db:migrate-save -- --name "initial version"`, `db:migrate-up`, then `seed`); afterwards create migrations with `npm run db:migrate-save -- --name ` and apply via `npm run db:migrate-up`/`npm run seed`. 6. **Start the service** with `npm run start` (servers) or `npm run start` from `apps/ecommerce-admin` after ensuring `VITE_REACT_APP_SERVER_URL` points at the running API. 7. **Alternative container path:** `npm run compose:up` builds & runs the service container using the provided `Dockerfile` and compose file. ## ๐Ÿ”— Messaging & Integrations - **Kafka topics (from `README.md`):** `order.create.v1`, `order.update.v1`, `product.create.v1`, `product.update.v1`. - - `apps/ecommerce-server` sends messages on those topics (see `src/kafka/kafka.producer.service.ts`). - - `apps/logistic-server` consumes the same topics (`src/kafka/kafka.service.ts`). + - `apps/ecommerce-server` is the Kafka producer emitting those topics (see `src/kafka/kafka.producer.service.ts`). + - `apps/logistic-server` is the Kafka consumer for those topics and relays workflows through its NATS bridge (`src/kafka/kafka.service.ts`, `src/nats/`). - **NATS (logistics):** `apps/logistic-server/docker-compose.dev.yml` defines a `nats` container, and the service implements handlers in `src/nats/` (`nats.module.ts`, `nats.service.ts`, `topics.ts`). Kafka and NATS clients are wired in `src/connectMicroservices.ts`. ## โœ… Testing & Quality From 16803c950df280a3e23c0c4709cc393e65a55398 Mon Sep 17 00:00:00 2001 From: overcut Date: Thu, 22 Jan 2026 00:08:44 +0000 Subject: [PATCH 7/7] docs: update AGENTS.md --- AGENTS.md | 40 ++++++++++++++++++++++------------------ 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b72d6d6..ebab66e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,7 @@ - **ecommerce-server:** NestJS + PostgreSQL + JWT + Kafka producer topics for order & product lifecycle. - **logistic-server:** NestJS + MySQL + HTTP Basic Auth + Kafka consumers + dedicated NATS integration for logistics workflows. - **ecommerce-admin:** React Admin on Vite, consuming the ecommerce API via `VITE_REACT_APP_SERVER_URL`. +- Current stack alignment: NestJS 10, Prisma 5, PostgreSQL, MySQL, KafkaJS, NATS, React 18, React Admin 5, Vite 4, Apollo Client, Sass, Jest/ts-jest, ESLint, Prettier, Docker Compose. - Toolchain versions (from the app-level `package.json` files): - Backends run on NestJS `10.2.x`, Prisma `5.4.x`, TypeScript `5.4.x`, KafkaJS `2.2.x`, npm-run-all `4.1.x`, and (logistics) NATS `2.17.x`. - The admin UI uses React `18.3.x`, React Admin `5.1.x`, Apollo Client `3.6.x`, Vite `4.3.x`, and TypeScript `5.1.x`. @@ -58,6 +59,8 @@ | `KAFKA_GROUP_ID` | Kafka consumer group ID for this service. | `ecommerce` | same | | `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | same | +- **Prisma workflow:** After editing `prisma/schema.prisma`, always run `npm run prisma:generate` โžœ `npm run db:migrate-save -- --name ` โžœ `npm run db:migrate-up` โžœ `npm run seed` to keep the client, migrations, and fixtures in sync. + ### ๐Ÿšš logistic-server (`apps/logistic-server`) - **Role:** Warehouse & shipment service secured with HTTP Basic auth, using MySQL storage, Kafka consumers, and NATS-based logistics messaging (`src/nats/`). - **Core stack:** NestJS 10.2.x + Prisma 5.4.x, MySQL, KafkaJS 2.2.x consumer, NATS 2.17.x client, Swagger, Jest. @@ -82,12 +85,14 @@ | `KAFKA_ENABLE_SSL` | Toggle (`true`/`false`) controlling SSL usage for Kafka connections. | `false` | `apps/logistic-server/.env` | | `NATS_SERVERS` | Comma-separated NATS server endpoints. Default `.env` value is `localhost:4222`, but the NATS factory consumes the string as-isโ€”provide fully qualified entries like `nats://host:4222` when not using the compose default. | `localhost:4222` | `apps/logistic-server/.env` (mirrors `docker-compose.dev.yml`) | +- **Prisma workflow:** Mirror the backend cadence: `npm run prisma:generate` โžœ `npm run db:migrate-save -- --name ` โžœ `npm run db:migrate-up` โžœ `npm run seed` whenever the schema or seed data evolves. + ### ๐Ÿ–ฅ๏ธ ecommerce-admin (`apps/ecommerce-admin`) - **Role:** React Admin dashboard consuming the ecommerce GraphQL API; uses Vite for dev/build and React Admin resources under `src//`. - **Core stack:** React, React Admin, Apollo Client, Vite, TypeScript, ESLint, Prettier, Sass. - **Core stack versions:** React 18.3.x / React Admin 5.1.x / Vite 4.3.x / TypeScript 5.1.x. - **Local infra:** Expects the ecommerce server running; `VITE_REACT_APP_SERVER_URL` must point to that host/port. -- **Heads-up:** `apps/ecommerce-admin/README.md` still references Create React Appโ€”consult `apps/ecommerce-admin/package.json` and `.env` for the authoritative Vite scripts/envs (including `VITE_REACT_APP_SERVER_URL`). +- **Env naming:** All frontend env vars follow the Vite convention (`VITE_...`), so rely on `apps/ecommerce-admin/package.json` / `.env` as the source of truth and ignore legacy Create React App wording. | Name | Description | Default / Notes | Source | | --- | --- | --- | --- | @@ -96,6 +101,8 @@ ## ๐Ÿ› ๏ธ Tooling & Scripts ### Backend services (`apps/ecommerce-server`, `apps/logistic-server`) +- **Prereq:** Bring up the Dockerized infra first (`npm run docker:dev`) so PostgreSQL/MySQL, Kafka, kafka-ui, and (for logistics) NATS are available before any Prisma/migration/test command. + | Script | Purpose | File | | --- | --- | --- | | `npm run start` / `start:watch` / `start:debug` | Run NestJS server (optionally watch/debug). | `apps/*-server/package.json` | @@ -125,20 +132,20 @@ ## ๐Ÿš€ Development Workflow 1. **Pick a service directory** (e.g., `cd apps/ecommerce-server`) and copy/adjust the provided `.env` file; never share sensitive overrides. 2. **Install dependencies** with `npm install` inside that service. -3. **Generate Prisma artifacts** via `npm run prisma:generate` (backends only) when schemas change. -4. **Provision local infra** with `npm run docker:dev` to bring up the serviceโ€™s database, Kafka stack, and (for logistics) NATS & Adminer. -5. **Initialize data** using `npm run db:init` only for first-time bootstrap (runs `db:migrate-save -- --name "initial version"`, `db:migrate-up`, then `seed`); afterwards create migrations with `npm run db:migrate-save -- --name ` and apply via `npm run db:migrate-up`/`npm run seed`. +3. **Prisma workflow (backends):** When schemas or seeds change, run `npm run prisma:generate` โžœ `npm run db:migrate-save -- --name ` โžœ `npm run db:migrate-up` โžœ `npm run seed` to keep clients, migrations, and fixtures aligned. +4. **Provision local infra** with `npm run docker:dev` **before** any migrations, seeds, or Jest runs so PostgreSQL/MySQL, Kafka, and (for logistics) NATS/Adminer are online. +5. **Initialize data** using `npm run db:init` only for first-time bootstrap (chains the Prisma workflow with a default migration name); for later changes stick to the workflow above with descriptive migration names. 6. **Start the service** with `npm run start` (servers) or `npm run start` from `apps/ecommerce-admin` after ensuring `VITE_REACT_APP_SERVER_URL` points at the running API. 7. **Alternative container path:** `npm run compose:up` builds & runs the service container using the provided `Dockerfile` and compose file. ## ๐Ÿ”— Messaging & Integrations - **Kafka topics (from `README.md`):** `order.create.v1`, `order.update.v1`, `product.create.v1`, `product.update.v1`. - - `apps/ecommerce-server` is the Kafka producer emitting those topics (see `src/kafka/kafka.producer.service.ts`). - - `apps/logistic-server` is the Kafka consumer for those topics and relays workflows through its NATS bridge (`src/kafka/kafka.service.ts`, `src/nats/`). -- **NATS (logistics):** `apps/logistic-server/docker-compose.dev.yml` defines a `nats` container, and the service implements handlers in `src/nats/` (`nats.module.ts`, `nats.service.ts`, `topics.ts`). Kafka and NATS clients are wired in `src/connectMicroservices.ts`. + - `apps/ecommerce-server` **produces** these events via `src/kafka/kafka.producer.service.ts`. + - `apps/logistic-server` **consumes** the same topics with `src/kafka/kafka.service.ts` and forwards logistics updates downstream through its NATS bridge (`src/nats/`). +- **NATS (logistics):** `apps/logistic-server/docker-compose.dev.yml` defines a `nats` container, and the service publishes/handles topics from `src/nats/topics.ts` via `nats.module.ts` / `nats.service.ts` to propagate the Kafka-derived events. Kafka and NATS clients are wired together in `src/connectMicroservices.ts`. ## โœ… Testing & Quality -- **Backends:** Run `npm run test` inside each server to execute Jest suites configured via `ts-jest` (`package.json > jest`). Domain-focused specs live under `apps/ecommerce-server/src/tests/` and `apps/logistic-server/src/tests/` (e.g., `auth/token.service.spec.ts`, `health/health.service.spec.ts`). +- **Backends:** Run `npm run test` inside each server to execute Jest suites configured via `ts-jest` (`package.json > jest`). Domain-focused specs live under `apps/ecommerce-server/src/tests/` and `apps/logistic-server/src/tests/` (e.g., `auth/token.service.spec.ts`, `health/health.service.spec.ts`). Always keep the `npm run docker:dev` stack running first so the PostgreSQL/MySQL/Kafka/NATS dependencies are available to the tests. - **Frontend:** While no standalone `test` script is declared, quality gates rely on `npm run type-check`, `npm run lint`, `npm run format`, and `npm run build`. The Vite/React Testing Library setup is scaffolded in `src/setupTests.ts` should you add tests. - **Data prep:** Use `npm run seed` (servers) for deterministic fixtures before running suites; ensure Dockerized databases and brokers are already healthy. @@ -192,16 +199,13 @@ docker-compose -f docker-compose.dev.yml down --volumes ## ๐Ÿ“š Reference Examples | Path | Why it matters | | --- | --- | -| `apps/ecommerce-admin/src/pages/Dashboard.tsx` | Minimal React Admin dashboard pattern with Material UI components. | -| `apps/ecommerce-admin/src/data-provider/graphqlDataProvider.ts` | Apollo-powered data provider wiring for GraphQL resources. | -| `apps/ecommerce-server/src/order/` | Typical NestJS module/resolver/service triple for a domain resource. | -| `apps/ecommerce-server/src/kafka/kafka.producer.service.ts` | Implementation of Kafka producers emitting order/product events. | -| `apps/logistic-server/src/kafka/kafka.service.ts` | Kafka consumer setup for receive-pattern workflows. | -| `apps/logistic-server/src/nats/` | Authoritative NATS wiring (module, topics, microservice bootstrap) for complex logistics messaging. | -| `apps/logistic-server/src/warehouse/` | Generated `base/` DTOs plus adjacent custom controllers/services illustrating the layering pattern. | -| `apps/ecommerce-server/src/tests/auth/token.service.spec.ts` | Example Jest spec exercising auth logic. | -| `apps/logistic-server/src/tests/auth/token.service.spec.ts` | Logistics-side auth test mirroring backend conventions. | -| `apps/logistic-server/docker-compose.dev.yml` | Comprehensive dev infra stack (MySQL, Adminer, Kafka, kafka-ui, NATS) used across backend workflows. | +| `apps/ecommerce-admin/src/pages/Dashboard.tsx` | Minimal React Admin dashboard wiring that shows the default layout/components pattern. | +| `apps/ecommerce-server/src/tests/auth/token.service.spec.ts` | Jest spec demonstrating how backend auth services are exercised with ts-jest. | +| `apps/ecommerce-server/src/order/` | Canonical example of an Amplication-generated NestJS module (controller/service/resolver + `base/`). | +| `apps/ecommerce-admin/src/data-provider/graphqlDataProvider.ts` | Apollo Client-backed data provider bridging React Admin resources to the ecommerce GraphQL API. | +| `apps/logistic-server/src/nats/` | Full NATS bridge (module/service/topics) that relays Kafka-consumed events to downstream systems. | +| `apps/logistic-server/docker-compose.dev.yml` | Source of record for the backend dev stack (MySQL, Adminer, Kafka trio, kafka-ui, NATS). | +| `apps/ecommerce-server/scripts/customSeed.ts` | Template for extending the default Prisma seeding pipeline with custom data fixtures. | ## ๐Ÿ”— Additional Resources - [Root README](README.md) โ€” high-level summary plus Kafka topic definitions.