How codesbydipkhan/ims_v01 works
1. Overall shape
- This is a two-tier internal management system for NextEd Advisors.
- The frontend is a Next.js App Router app on port 3000.
- The backend is a NestJS REST API on port 3001.
- Persistence is PostgreSQL via TypeORM; files are stored locally under backend/storage/invoices.
2. Frontend boundary and route structure
- The UI is organized by business area rather than by generic pages.
- Main route groups include:
- Students: listing, add/register flow, collected/student detail pages, transactions
- Invoices: list, create, internal invoices
- Dashboard: performance and confidential sections
- The route tree suggests a multi-step operational app, not a content site.
3. Frontend access control
- Authentication is enforced in the UI with AuthGuard and ConfidentialGuard.
- The frontend stores the JWT in sessionStorage and uses it when calling the API.
- Confidential pages are separated from general dashboard pages by a dedicated confidential layout.
4. Frontend-to-backend integration
- src/lib/api.ts is the client-side API boundary.
- The frontend talks directly to the NestJS REST endpoints using the NEXT_PUBLIC_API_URL environment variable.
- This is a thin presentation layer: most business rules live in the backend.
5. Backend module architecture
- The backend is split into NestJS feature modules:
- auth
- students
- employees
- counselors
- countries
- currency
- invoices
- io
- salary
- Each module follows the standard Nest pattern of controller + service + DTOs, with TypeORM entities in src/entities.
6. Core data model
- The important persisted entities are:
- User for login
- Student, StudentInfo, StudentFollowUp
- Employee, Counselor, Country
- Invoice
- Salary
- IoEntry for income/expense tracking
- Sequence for generated identifiers
- This indicates a workflow-centric domain model, with students and finance as the primary records.
7. Authentication flow
- Login happens through POST /auth/login.
- The backend uses JWT auth with a NestJS strategy and guard.
- A Public decorator marks unauthenticated routes.
- The current design is database-backed credential verification with bcrypt-hashed passwords, not SSO or external identity.
8. Student lifecycle
- Student registration is a staged process in the UI:
- collect info
- register
- view collected record
- view full student detail
- track transactions
- Backend endpoints support create, list, detail, and partial update operations.
- Student IDs are auto-generated using business prefixes and a sequence mechanism, which means identity generation is part of the application logic, not the database alone.
9. Invoice and PDF pipeline
- Invoice creation is handled by the backend and produces both a database record and a PDF file.
- PdfService uses Puppeteer to render PDFs.
- Generated PDFs are stored locally and can be streamed back inline from GET /invoices/:id/pdf.
- The README notes a future Firebase Storage swap point, but the current architecture is local file storage.
10. Currency and finance-related flow
- The backend has a dedicated currency module for live conversion to BDT.
- It prefers an exchange-rate API key if configured, otherwise falls back to open.er-api.com.
- This conversion capability feeds invoice-related calculations and finance views.
11. Operational/confidential subsystems
- The dashboard includes performance and confidential areas, implying separate access levels for sensitive financial reporting.
- io and salary modules suggest internal bookkeeping and payroll-style records.
- These areas likely consume the same core entities but are isolated at the route/UI level.
12. Startup and environment dependencies
- The backend reads database, JWT, exchange-rate, and PDF storage settings from backend/.env.
- TypeORM is configured with synchronize: true, so schema creation happens automatically on startup.
- A seed script initializes the system with an admin user, countries, and employees, which is important for first-run architecture.
13. External and runtime dependencies that matter
- PostgreSQL is the primary durable store.
- Puppeteer/Chromium is a runtime dependency for PDF generation.
- Exchange-rate HTTP APIs are used for live currency conversion.
- No queueing layer, cache, or separate reporting service is present in the repository.
14. What to draw in an architecture diagram
- Show the Next.js frontend as the presentation layer with guarded routes.
- Show the NestJS API as the central business logic layer, split into domain modules.
- Connect the backend to PostgreSQL, local PDF storage, and external exchange-rate APIs.
- Highlight the data flows for login, student registration, invoice creation/PDF generation, and finance/confidential reporting as the main application paths.
Main entry points: main.ts Nest API · invoices Invoices module · app Next.js app · src Finance modules
Components 16
Frontend
Next.js presentation layer with guarded operational routes.
- Next.js app · Frontend shell for the internal management system.
frontend/src/app - Students · Student onboarding, collected records, detail views, and transactions.
frontend/src/app/students - Invoices · Invoice listing, creation, and internal invoice flows.
frontend/src/app/invoices - Dashboard · Performance and confidential dashboard areas.
frontend/src/app/dashboard - Route guards · AuthGuard and ConfidentialGuard enforce UI access control.
frontend/src/components - API client · Client-side API boundary using the configured API URL and session JWT.
frontend/src/lib/api.ts
Backend
NestJS API and domain modules.
- Nest API · Backend application and HTTP entrypoint.
backend/src/main.ts - Auth · Login, JWT strategy, public routes, and credential verification.
backend/src/auth - Students module · Student registration, detail, and update workflows.
backend/src/students - Invoices module · Invoice creation, internal invoices, and PDF generation.
backend/src/invoices - Finance modules · Employees, counselors, countries, currency, io, and salary domain modules.
backend/src - Entities · Persistent domain models including users, students, invoices, finance, and sequences.
backend/src/entities
Data & runtime
Persistence, file storage, and external runtime dependencies.
- PostgreSQL · Primary durable store accessed through TypeORM.
- Invoice files · Generated invoice PDFs stored under backend/storage/invoices.
backend/storage/invoices - Rates API · Fallback/live exchange-rate source used by currency conversion.
- Puppeteer · HTML-to-PDF rendering runtime used by invoice generation.
Connections 23
- Next.js app → Students: routes · Business-area route tree for student workflows.
- Next.js app → Invoices: routes · Invoice-focused UI flows.
- Next.js app → Dashboard: routes · Dashboard and sensitive reporting areas.
- Students → Route guards: protected by · Student routes require UI authentication.
- Dashboard → Route guards: protected by · Confidential dashboard routes are separately guarded.
- Next.js app → API client: calls · Frontend uses the API client as its backend boundary.
- API client → Nest API: HTTP · Direct REST calls to the NestJS backend.
- Nest API → Auth: loads · Authentication feature module.
- Nest API → Students module: loads · Student workflow module.
- Nest API → Invoices module: loads · Invoice and PDF workflow module.
- Nest API → Finance modules: loads · Operational finance-related modules.
- Nest API → Entities: uses · Shared persistence models.
- Auth → PostgreSQL: reads/writes · Credential verification and user lookup.
- Students module → PostgreSQL: reads/writes · Student records and follow-up data.
- Students module → Entities: maps to · Student, StudentInfo, StudentFollowUp, and Sequence entities.
- Invoices module → Puppeteer: renders PDFs · Invoice PDFs are generated from backend templates.
- Invoices module → Invoice files: stores files · Generated PDFs are persisted locally.
- Invoices module → PostgreSQL: reads/writes · Invoice records and identifiers.
- Finance modules → Rates API: fetches rates · Currency conversion uses live exchange-rate services.
- Finance modules → PostgreSQL: reads/writes · Finance, employee, counselor, and IO records.
- Finance modules → Entities: maps to · Employee, Counselor, Country, Salary, and IoEntry entities.
- Auth → API client: JWT session · Frontend stores and sends the token from sessionStorage.
- Invoices module → Invoices: serves · Invoice creation and PDF views are driven by backend endpoints.