# dilasathapa/provisional-certificate-portal architecture

> Architecture diagram of the GitHub repository dilasathapa/provisional-certificate-portal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dilasathapa/provisional-certificate-portal
- Repository: https://github.com/dilasathapa/provisional-certificate-portal

## Overview

The Provisional Certificate Portal supports account access, authenticated application creation and review, required PDF uploads, submission, and acknowledgment downloads. The frontend guides applicants through these stages and presents application status; the Express API enforces authentication and ownership while application services coordinate persistence and PDF storage. The README documents MongoDB and S3 roles. Some subsystem links rely on that documentation or SOURCE INDEX references because their implementation files were not excerpted; uncertain connections are omitted.

Main entry points: [`frontend/src/pages/applications/NewApplication.jsx`](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/NewApplication.jsx) (Application wizard), [`backend/src/services/application.service.js`](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/application.service.js) (Application service), [`frontend/src/routes/AppRoutes.jsx`](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/routes/AppRoutes.jsx) (Page routing), [`backend/src/routes/application.routes.js`](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/routes/application.routes.js) (Application routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Applicant web app"]
  node_webapp["React portal<br/>[App.jsx]"]
  node_authpages["Sign in and signup<br/>[Login.jsx]"]
  node_signup["Registration page<br/>[Signup.jsx]"]
  node_authstate["Session state<br/>[AuthContext.jsx]"]
  node_routes["Page routing<br/>[AppRoutes.jsx]"]
  node_dashboard["Application dashboard<br/>[Dashboard.jsx]"]
  node_newapp["Application wizard<br/>[NewApplication.jsx]"]
  node_personal["Personal details"]
  node_documentsstep["Document upload step<br/>[DocumentsStep.jsx]"]
  node_review["Review and submit<br/>[ReviewStep.jsx]"]
  node_appapi["Application API client<br/>[application.api.js]"]
  node_docapi["Document API client<br/>[document.api.js]"]
  node_axios["HTTP client<br/>[axios.js]"]
end

subgraph group_api["API and access"]
  node_backend["Express API<br/>[app.js]"]
  node_authroutes["Authentication routes<br/>[auth.routes.js]"]
  node_authcontroller["Authentication handlers<br/>[auth.controller.js]"]
  node_authservice["Authentication service<br/>[auth.service.js]"]
  node_authmw["JWT access check<br/>[auth.middleware.js]"]
  node_approutes["Application routes"]
  node_appcontroller["Application handlers"]
  node_docroutes["Document routes<br/>[document.routes.js]"]
  node_doccontroller["Document handlers"]
end

subgraph group_workflow["Application workflow"]
  node_appservice["Application service"]
  node_pdfservice["Acknowledgment generation"]
  node_reference["Reference generation<br/>[reference.util.js]"]
  node_docservice["Document service"]
end

subgraph group_persistence["Persistence and files"]
  node_applicationmodel["Application records<br/>[Application.js]"]
  node_documentmodel["Document records<br/>[Document.js]"]
  node_usermodel["User records<br/>[User.js]"]
  node_mongodb[("MongoDB")]
  node_storage["S3 storage service<br/>[storage.service.js]"]
  node_s3[("Amazon S3")]
end

node_applicant(("Applicant"))

node_applicant -->|"uses"| node_webapp
node_webapp -->|"provides session"| node_authstate
node_webapp -->|"renders routes"| node_routes
node_routes -->|"routes to"| node_authpages
node_routes -->|"routes to"| node_signup
node_routes -->|"routes to"| node_dashboard
node_routes -->|"routes to"| node_newapp
node_authpages -->|"uses"| node_authstate
node_signup -->|"uses"| node_authstate
node_authstate -->|"calls"| node_axios
node_newapp -->|"renders"| node_personal
node_newapp -->|"renders"| node_documentsstep
node_newapp -->|"renders"| node_review
node_newapp -->|"calls"| node_appapi
node_newapp -->|"calls"| node_docapi
node_appapi -->|"uses"| node_axios
node_docapi -->|"uses"| node_axios
node_appapi -->|"sends REST requests"| node_approutes
node_docapi -->|"sends REST requests"| node_docroutes
node_dashboard -->|"retrieves applications"| node_approutes
node_backend -->|"mounts"| node_authroutes
node_backend -->|"mounts"| node_approutes
node_backend -->|"mounts"| node_docroutes
node_authroutes -->|"dispatches"| node_authcontroller
node_approutes -->|"authenticates"| node_authmw
node_approutes -->|"dispatches"| node_appcontroller
node_docroutes -->|"authenticates"| node_authmw
node_docroutes -->|"dispatches"| node_doccontroller
node_authcontroller -->|"calls"| node_authservice
node_authmw -->|"looks up user"| node_usermodel
node_appcontroller -->|"calls"| node_appservice
node_doccontroller -->|"calls"| node_docservice
node_appservice -->|"creates and queries"| node_applicationmodel
node_appservice -->|"checks required files"| node_documentmodel
node_appservice -->|"generates reference"| node_reference
node_appservice -->|"generates acknowledgment"| node_pdfservice
node_appservice -->|"requests signed URL"| node_storage
node_docservice -->|"stores metadata"| node_documentmodel
node_docservice -->|"uploads files"| node_storage
node_pdfservice -.->|"stores PDF"| node_storage
node_applicationmodel -->|"persists"| node_mongodb
node_documentmodel -->|"persists"| node_mongodb
node_usermodel -->|"persists"| node_mongodb
node_storage -->|"reads and writes"| node_s3

click node_webapp "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/App.jsx"
click node_authpages "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/Login.jsx"
click node_signup "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/Signup.jsx"
click node_authstate "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/context/AuthContext.jsx"
click node_routes "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/routes/AppRoutes.jsx"
click node_dashboard "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/Dashboard.jsx"
click node_newapp "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/NewApplication.jsx"
click node_personal "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/steps/PersonalDetailsStep.jsx"
click node_documentsstep "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/steps/DocumentsStep.jsx"
click node_review "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/steps/ReviewStep.jsx"
click node_appapi "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/api/application.api.js"
click node_docapi "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/api/document.api.js"
click node_axios "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/api/axios.js"
click node_backend "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/app.js"
click node_authroutes "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/routes/auth.routes.js"
click node_authcontroller "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/controllers/auth.controller.js"
click node_authservice "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/auth.service.js"
click node_authmw "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/middleware/auth.middleware.js"
click node_approutes "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/routes/application.routes.js"
click node_appcontroller "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/controllers/application.controller.js"
click node_docroutes "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/routes/document.routes.js"
click node_doccontroller "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/controllers/document.controller.js"
click node_appservice "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/application.service.js"
click node_pdfservice "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/application-pdf.service.js"
click node_reference "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/utils/reference.util.js"
click node_docservice "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/document.service.js"
click node_applicationmodel "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/models/Application.js"
click node_documentmodel "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/models/Document.js"
click node_usermodel "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/models/User.js"
click node_storage "https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/storage.service.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_authpages,node_signup,node_authstate,node_routes,node_dashboard,node_newapp,node_personal,node_documentsstep,node_review,node_appapi,node_docapi,node_axios toneBlue
class node_backend,node_authroutes,node_authcontroller,node_authservice,node_authmw,node_approutes,node_appcontroller,node_docroutes,node_doccontroller toneAmber
class node_appservice,node_pdfservice,node_reference,node_docservice toneMint
class node_applicationmodel,node_documentmodel,node_usermodel,node_mongodb,node_storage,node_s3 toneRose
class node_applicant toneIndigo
```

## Components

### Applicant web app

- [React portal](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign in and signup](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Registration page](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/Signup.jsx): `frontend/src/pages/Signup.jsx`
- [Session state](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Page routing](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/routes/AppRoutes.jsx): `frontend/src/routes/AppRoutes.jsx`
- [Application dashboard](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/Dashboard.jsx): `frontend/src/pages/Dashboard.jsx`
- [Application wizard](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/NewApplication.jsx): `frontend/src/pages/applications/NewApplication.jsx`
- [Personal details](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/steps/PersonalDetailsStep.jsx): `frontend/src/pages/applications/steps/PersonalDetailsStep.jsx`
- [Document upload step](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/steps/DocumentsStep.jsx): `frontend/src/pages/applications/steps/DocumentsStep.jsx`
- [Review and submit](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/pages/applications/steps/ReviewStep.jsx): `frontend/src/pages/applications/steps/ReviewStep.jsx`
- [Application API client](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/api/application.api.js): `frontend/src/api/application.api.js`
- [Document API client](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/api/document.api.js): `frontend/src/api/document.api.js`
- [HTTP client](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/frontend/src/api/axios.js): `frontend/src/api/axios.js`

### API and access

- [Express API](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/app.js): `backend/src/app.js`
- [Authentication routes](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`
- [Authentication handlers](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/controllers/auth.controller.js): `backend/src/controllers/auth.controller.js`
- [Authentication service](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/auth.service.js): `backend/src/services/auth.service.js`
- [JWT access check](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/middleware/auth.middleware.js): `backend/src/middleware/auth.middleware.js`
- [Application routes](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/routes/application.routes.js): `backend/src/routes/application.routes.js`
- [Application handlers](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/controllers/application.controller.js): `backend/src/controllers/application.controller.js`
- [Document routes](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/routes/document.routes.js): `backend/src/routes/document.routes.js`
- [Document handlers](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/controllers/document.controller.js): `backend/src/controllers/document.controller.js`

### Application workflow

- [Application service](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/application.service.js): `backend/src/services/application.service.js`
- [Acknowledgment generation](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/application-pdf.service.js): `backend/src/services/application-pdf.service.js`
- [Reference generation](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/utils/reference.util.js): `backend/src/utils/reference.util.js`
- [Document service](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/document.service.js): `backend/src/services/document.service.js`

### Persistence and files

- [Application records](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/models/Application.js): `backend/src/models/Application.js`
- [Document records](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/models/Document.js): `backend/src/models/Document.js`
- [User records](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/models/User.js): `backend/src/models/User.js`
- **MongoDB**
- [S3 storage service](https://github.com/dilasathapa/provisional-certificate-portal/blob/main/backend/src/services/storage.service.js): `backend/src/services/storage.service.js`
- **Amazon S3**

### Other components

- **Applicant**

## Connections

- Applicant → React portal: uses (evidence: `README.md`)
- React portal → Session state: provides session (evidence: `frontend/src/App.jsx`)
- React portal → Page routing: renders routes (evidence: `frontend/src/App.jsx`)
- Page routing → Sign in and signup: routes to (evidence: `frontend/src/routes/AppRoutes.jsx`)
- Page routing → Registration page: routes to (evidence: `frontend/src/routes/AppRoutes.jsx`)
- Page routing → Application dashboard: routes to (evidence: `frontend/src/routes/AppRoutes.jsx`)
- Page routing → Application wizard: routes to (evidence: `frontend/src/routes/AppRoutes.jsx`)
- Sign in and signup → Session state: uses (evidence: `frontend/src/pages/Login.jsx`)
- Registration page → Session state: uses (evidence: `frontend/src/pages/Signup.jsx`)
- Session state → HTTP client: calls (evidence: `frontend/src/context/AuthContext.jsx`)
- Application wizard → Personal details: renders (evidence: `frontend/src/pages/applications/NewApplication.jsx`)
- Application wizard → Document upload step: renders (evidence: `frontend/src/pages/applications/NewApplication.jsx`)
- Application wizard → Review and submit: renders (evidence: `frontend/src/pages/applications/NewApplication.jsx`)
- Application wizard → Application API client: calls (evidence: `frontend/src/pages/applications/NewApplication.jsx`)
- Application wizard → Document API client: calls (evidence: `frontend/src/pages/applications/NewApplication.jsx`)
- Application API client → HTTP client: uses (evidence: `frontend/src/api/application.api.js`)
- Document API client → HTTP client: uses (evidence: `frontend/src/api/document.api.js`)
- Application API client → Application routes: sends REST requests (evidence: `README.md`)
- Document API client → Document routes: sends REST requests (evidence: `README.md`)
- Application dashboard → Application routes: retrieves applications (evidence: `README.md`)
- Express API → Authentication routes: mounts (evidence: `backend/src/app.js`)
- Express API → Application routes: mounts (evidence: `backend/src/app.js`)
- Express API → Document routes: mounts (evidence: `backend/src/app.js`)
- Authentication routes → Authentication handlers: dispatches (evidence: `backend/src/routes/auth.routes.js`)
- Application routes → JWT access check: authenticates (evidence: `backend/src/routes/application.routes.js`)
- Application routes → Application handlers: dispatches (evidence: `backend/src/routes/application.routes.js`)
- Document routes → JWT access check: authenticates (evidence: `backend/src/routes/document.routes.js`)
- Document routes → Document handlers: dispatches (evidence: `backend/src/routes/document.routes.js`)
- Authentication handlers → Authentication service: calls (evidence: `backend/src/controllers/auth.controller.js`)
- JWT access check → User records: looks up user (evidence: `backend/src/middleware/auth.middleware.js`)
- Application handlers → Application service: calls (evidence: `backend/src/controllers/application.controller.js`)
- Document handlers → Document service: calls (evidence: `backend/src/controllers/document.controller.js`)
- Application service → Application records: creates and queries (evidence: `backend/src/services/application.service.js`)
- Application service → Document records: checks required files (evidence: `backend/src/services/application.service.js`)
- Application service → Reference generation: generates reference (evidence: `backend/src/services/application.service.js`)
- Application service → Acknowledgment generation: generates acknowledgment (evidence: `backend/src/services/application.service.js`)
- Application service → S3 storage service: requests signed URL (evidence: `backend/src/services/application.service.js`)
- Document service → Document records: stores metadata (evidence: `backend/src/services/document.service.js`)
- Document service → S3 storage service: uploads files (evidence: `backend/src/services/document.service.js`)
- Acknowledgment generation → S3 storage service: stores PDF
- Application records → MongoDB: persists (evidence: `README.md`)
- Document records → MongoDB: persists (evidence: `README.md`)
- User records → MongoDB: persists (evidence: `README.md`)
- S3 storage service → Amazon S3: reads and writes (evidence: `backend/src/services/storage.service.js`)
