effuone/nodemap

Purpose and Topology

Nodemap is a two-application SaaS for generating and managing visual, node-based learning roadmaps. The React browser client lives in apps/web; the NestJS API lives in apps/api. Development infrastructure provisions PostgreSQL and Redis through docker-compose.dev.yml.

Application Entry Points

The API bootstraps NestJS from apps/api/src/main.ts, assembling feature modules in apps/api/src/app.module.ts. The web client boots React in apps/web/src/main.tsx and defines application navigation in apps/web/src/routes.tsx. Primary user surfaces are authentication, home, and roadmap views under apps/web/src/pages/AuthPage.tsx, apps/web/src/pages/HomePage.tsx, and apps/web/src/pages/RoadmapPage.tsx.

API Boundary and Cross-Cutting Runtime

NestJS exposes HTTP endpoints with centralized environment validation, request logging, and exception handling in apps/api/src/core/env-validation-schema.ts, apps/api/src/core/logger.middleware.ts, and apps/api/src/core/http.exception-filter.ts. Health checking is a distinct operational boundary through apps/api/src/health/health.controller.ts and database health support in apps/api/src/database/database.health.ts.

Identity and Access Control

Authentication is a dedicated API subsystem: controllers/services in apps/api/src/auth/auth.controller.ts and apps/api/src/auth/auth.service.ts, backed by JWT and refresh-token Passport strategies in apps/api/src/auth/strategies/jwt.strategy.ts and apps/api/src/auth/strategies/jwt-refresh-token.strategy.ts. Protected API access is enforced by guards. The browser holds auth state and applies request interception through apps/web/src/lib/auth/auth.context.tsx, apps/web/src/lib/auth/auth.interceptor.ts, and apps/web/src/lib/auth/auth.layout.tsx.

Persistence and User Domain

PostgreSQL is the durable system of record, modeled with Prisma in apps/api/prisma/schema.prisma and accessed through apps/api/src/database/database.service.ts. The database module owns connection and database exception boundaries (apps/api/src/database/database.module.ts, apps/api/src/database/database.exception-filter.ts). User-specific operations are grouped in apps/api/src/user/user.module.ts and apps/api/src/user/user.service.ts.

Roadmap Generation and Realtime Delivery

The roadmap subsystem is the core domain boundary: it accepts create/update DTOs, persists/manipulates roadmap entities, and delivers graph updates through a gateway. Its principal files are apps/api/src/roadmap/roadmap.module.ts, apps/api/src/roadmap/roadmap.service.ts, and apps/api/src/roadmap/roadmap.gateway.ts. The README identifies OpenAI content generation and Redis/BullMQ background jobs as generation infrastructure; Redis is externally provisioned, while the visible roadmap structure seed/template is apps/api/src/roadmap/struct.json.

Browser Graph Experience

The client calls backend/AI-facing functions in apps/web/src/api/getBrowserData.tsx and apps/web/src/api/getGPTDescription.tsx, then transforms generated content through apps/web/src/shared/utils/transformGPTObject/index.ts. React Flow-oriented graph rendering is decomposed into main/child node and edge components: apps/web/src/components/mainNode.tsx, apps/web/src/components/childNode.tsx, and apps/web/src/components/mainPathEdge.tsx. Generation interaction is centered on apps/web/src/components/generate-dialog.tsx.

Deployment Shape

The API has container and process definitions in apps/api/Dockerfile and apps/api/Procfile. The Vite frontend has Vercel deployment configuration at apps/web/vercel.json. Required external runtime services are PostgreSQL, Redis, and OpenAI; environment contracts are represented by apps/api/.env.example and apps/web/.env.example.