ajkizzy/nordic-atlas-dpp-prototype

1. This repository is split into two main runtime boundaries: a NestJS API in api/ and a React/Vite frontend in web/. The app is containerized with Docker and started via docker compose up --build, with the frontend served through Nginx in production and the API exposed on port 3000.

2. The backend is the system of record. It uses NestJS modules and controllers for domain areas like auth, users, products, batches, passport, evidence, and audit. Prisma is the ORM layer (api/src/prisma, api/prisma/schema.prisma) and migrations show the database evolves around batch/product passport data, audit logging, and evidence records.

3. The core business object appears to be the batch/product passport. batches is the central domain module and includes a co2-calculator.ts, which suggests environmental impact values are computed or aggregated there. products and users likely support the batch/passport administration and lookup flows around that core entity.

4. Public access is token-based. The README’s /resolve/[batchPublicToken] route maps to the public passport flow: a QR code or token is resolved by the frontend, then the API returns the public passport view for that batch. This is the main anonymous read path and the primary “scan → resolve → view passport” data flow.

5. Authenticated access is role-based. The backend has a dedicated auth module with JWT support, plus jwt.guard.ts, roles.decorator.ts, and roles.guard.ts. That implies the API enforces authorization centrally, with different data exposure for admin, B2B, internal, and regulator roles rather than a single universal passport response.

6. The frontend mirrors those visibility tiers in its component structure. There are separate passport renderers for PassportPublic, PassportB2B, PassportInternal, and PassportRegulator, plus RoleSwitcher and FieldVisibilityBadge. This suggests the UI progressively reveals more fields as role context changes, instead of using distinct applications.

7. The admin experience is isolated from the public passport flow. AdminDashboard.tsx and the README’s /admin path indicate a privileged operational surface for managing batches/tokens and inspecting data. The frontend likely logs in via /login, stores the JWT, and then calls authenticated API endpoints through web/src/api/client.ts.

8. Traceability and compliance are first-class subsystems. The audit module, together with migrations adding “audit_log_before_after,” indicates the backend records who changed what and captures previous/new values. The evidence module and its migration indicate supporting documentation or proof artifacts are attached to passport data, which is important for supply-chain claims.

9. The backend startup/initialization path includes seeding. api/prisma/seed.ts and the README’s mention of startup logs printing batch tokens show seeded demo data is part of the expected architecture. That makes the repo a proof-of-concept with deterministic sample entities and public tokens for testing.

10. From a deployment perspective, the frontend is a static SPA built with Vite and Tailwind/PostCSS, while the API is a Node service built with NestJS/TypeScript. The Nginx config in web/nginx.conf suggests the compiled SPA is served as static content, and the API is consumed over HTTP from the browser using the shared client in web/src/api/client.ts.

11. The key architectural boundary is therefore: browser UI on one side, authenticated REST-style API on the other, with Prisma-backed persistence beneath the API. The UI handles presentation and role-specific rendering; the API owns authorization, business rules, calculations, auditability, and data persistence.

12. For a diagram, the most important flows to show are: QR/token resolution to public passport; user login to JWT issuance; JWT-protected admin/B2B/internal/regulator reads; batch changes writing audit entries and possibly evidence records; and Prisma migrations/seed establishing the database state used by all of the above.