# mahammadafnan/cloudlockr architecture

> Architecture diagram of the GitHub repository mahammadafnan/cloudlockr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahammadafnan/cloudlockr
- Repository: https://github.com/mahammadafnan/cloudlockr

## Overview

CloudLockr is a cloud security posture management platform. Users sign in to the React workspace, inspect cloud assets and security findings, and can trigger scans, view posture/compliance results, download reports, or request AI remediation. The scan engine dispatches provider scanners, evaluates discovered resources against the rules registry, calculates posture, and records scan state. The README documents scheduling and alerting; the sampled scan engine also shows alert dispatch. Controller-to-route wiring and frontend API calls are not fully sampled, so uncertain links are omitted.

Main entry points: [`backend/src/utils/scanEngine.js`](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/scanEngine.js) (Scan engine), [`backend/src/app.js`](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/app.js) (Express API), [`backend/src/models`](https://github.com/mahammadafnan/cloudlockr/tree/main/backend/src/models) (Resource, finding, scan models), [`frontend/src/App.jsx`](https://github.com/mahammadafnan/cloudlockr/blob/main/frontend/src/App.jsx) (React workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web workspace"]
  node_workspace["React workspace<br/>[App.jsx]"]
  node_workspace_pages["Security pages"]
  node_auth_context["Auth context<br/>[AuthContext.jsx]"]
end

subgraph group_api["API and accounts"]
  node_api_app["Express API<br/>[app.js]"]
  node_auth_routes["Auth routes<br/>[authRoutes.js]"]
  node_auth_controller["Auth controller<br/>[authController.js]"]
  node_dashboard_routes["Dashboard routes<br/>[dashboardRoutes.js]"]
  node_dashboard_controller["Dashboard controller"]
  node_scan_routes["Scan routes<br/>[scanRoutes.js]"]
  node_scan_controller["Scan controller<br/>[scanController.js]"]
end

subgraph group_assessment["Security assessment"]
  node_scan_engine["Scan engine<br/>[scanEngine.js]"]
  node_scanners["Provider scanners"]
  node_rules["CIS rule registry<br/>[index.js]"]
  node_posture["Posture calculator"]
  node_models["Resource, finding, scan models"]
  node_scheduler["Background scheduler<br/>[scheduler.js]"]
  node_mailer["Alert mailer<br/>[mailer.js]"]
end

subgraph group_insights["Reports and remediation"]
  node_report_routes["Report routes<br/>[reportRoutes.js]"]
  node_report_controller["PDF reports"]
  node_ai_routes["AI routes<br/>[aiRoutes.js]"]
  node_ai_controller["AI remediation<br/>[aiController.js]"]
end

node_user(("Cloud security user"))
node_clouds{{"Cloud providers"}}
node_mongodb[("MongoDB")]
node_mail_service{{"SMTP service"}}
node_gemini{{"Gemini API"}}

node_user -->|"uses"| node_workspace
node_workspace -->|"routes to"| node_workspace_pages
node_workspace -->|"provides auth"| node_auth_context
node_workspace -->|"requests API"| node_api_app
node_api_app -->|"mounts"| node_auth_routes
node_api_app -->|"mounts"| node_dashboard_routes
node_api_app -->|"mounts"| node_scan_routes
node_api_app -->|"mounts"| node_report_routes
node_api_app -->|"mounts"| node_ai_routes
node_auth_routes -->|"dispatches"| node_auth_controller
node_auth_controller -->|"queries"| node_models
node_dashboard_routes -->|"dispatches"| node_dashboard_controller
node_dashboard_controller -->|"queries"| node_models
node_scan_routes -->|"dispatches"| node_scan_controller
node_scan_controller -->|"starts scan"| node_scan_engine
node_scheduler -->|"triggers scan"| node_scan_engine
node_scan_engine -->|"reads and writes"| node_models
node_models -->|"persists data"| node_mongodb
node_scan_engine -->|"dispatches"| node_scanners
node_scanners -->|"discovers assets"| node_clouds
node_scan_engine -->|"evaluates resources"| node_rules
node_scan_engine -->|"calculates posture"| node_posture
node_scan_engine -->|"dispatches alerts"| node_mailer
node_mailer -.->|"sends email"| node_mail_service
node_report_routes -->|"dispatches"| node_report_controller
node_report_controller -->|"reads records"| node_models
node_report_controller -->|"calculates posture"| node_posture
node_ai_routes -->|"dispatches"| node_ai_controller
node_ai_controller -->|"loads finding"| node_models
node_ai_controller -.->|"requests remediation"| node_gemini

click node_workspace "https://github.com/mahammadafnan/cloudlockr/blob/main/frontend/src/App.jsx"
click node_workspace_pages "https://github.com/mahammadafnan/cloudlockr/tree/main/frontend/src/pages"
click node_auth_context "https://github.com/mahammadafnan/cloudlockr/blob/main/frontend/src/context/AuthContext.jsx"
click node_api_app "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/app.js"
click node_auth_routes "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/authRoutes.js"
click node_auth_controller "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/authController.js"
click node_dashboard_routes "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/dashboardRoutes.js"
click node_dashboard_controller "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/dashboardController.js"
click node_scan_routes "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/scanRoutes.js"
click node_scan_controller "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/scanController.js"
click node_scan_engine "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/scanEngine.js"
click node_scanners "https://github.com/mahammadafnan/cloudlockr/tree/main/backend/src/scanners"
click node_rules "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/rules/index.js"
click node_posture "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/postureCalculator.js"
click node_models "https://github.com/mahammadafnan/cloudlockr/tree/main/backend/src/models"
click node_scheduler "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/scheduler.js"
click node_mailer "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/mailer.js"
click node_report_routes "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/reportRoutes.js"
click node_report_controller "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/reportController.js"
click node_ai_routes "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/aiRoutes.js"
click node_ai_controller "https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/aiController.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_workspace,node_workspace_pages,node_auth_context,node_user toneBlue
class node_api_app,node_auth_routes,node_auth_controller,node_dashboard_routes,node_dashboard_controller,node_scan_routes,node_scan_controller,node_mongodb toneAmber
class node_scan_engine,node_scanners,node_rules,node_posture,node_models,node_scheduler,node_mailer,node_gemini toneMint
class node_report_routes,node_report_controller,node_ai_routes,node_ai_controller toneRose
class node_clouds,node_mail_service toneIndigo
```

## Components

### Web workspace

- [React workspace](https://github.com/mahammadafnan/cloudlockr/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Security pages](https://github.com/mahammadafnan/cloudlockr/tree/main/frontend/src/pages): `frontend/src/pages`
- [Auth context](https://github.com/mahammadafnan/cloudlockr/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`

### API and accounts

- [Express API](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/app.js): `backend/src/app.js`
- [Auth routes](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/authRoutes.js): `backend/src/routes/authRoutes.js`
- [Auth controller](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/authController.js): `backend/src/controllers/authController.js`
- [Dashboard routes](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/dashboardRoutes.js): `backend/src/routes/dashboardRoutes.js`
- [Dashboard controller](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/dashboardController.js): `backend/src/controllers/dashboardController.js`
- [Scan routes](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/scanRoutes.js): `backend/src/routes/scanRoutes.js`
- [Scan controller](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/scanController.js): `backend/src/controllers/scanController.js`

### Security assessment

- [Scan engine](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/scanEngine.js): `backend/src/utils/scanEngine.js`
- [Provider scanners](https://github.com/mahammadafnan/cloudlockr/tree/main/backend/src/scanners): `backend/src/scanners`
- [CIS rule registry](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/rules/index.js): `backend/src/rules/index.js`
- [Posture calculator](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/postureCalculator.js): `backend/src/utils/postureCalculator.js`
- [Resource, finding, scan models](https://github.com/mahammadafnan/cloudlockr/tree/main/backend/src/models): `backend/src/models`
- [Background scheduler](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/scheduler.js): `backend/src/utils/scheduler.js`
- [Alert mailer](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/utils/mailer.js): `backend/src/utils/mailer.js`

### Reports and remediation

- [Report routes](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/reportRoutes.js): `backend/src/routes/reportRoutes.js`
- [PDF reports](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/reportController.js): `backend/src/controllers/reportController.js`
- [AI routes](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/routes/aiRoutes.js): `backend/src/routes/aiRoutes.js`
- [AI remediation](https://github.com/mahammadafnan/cloudlockr/blob/main/backend/src/controllers/aiController.js): `backend/src/controllers/aiController.js`

### Other components

- **Cloud security user**
- **Cloud providers**
- **MongoDB**
- **SMTP service**
- **Gemini API**

## Connections

- Cloud security user → React workspace: uses
- React workspace → Security pages: routes to
- React workspace → Auth context: provides auth
- React workspace → Express API: requests API
- Express API → Auth routes: mounts
- Express API → Dashboard routes: mounts
- Express API → Scan routes: mounts
- Express API → Report routes: mounts
- Express API → AI routes: mounts
- Auth routes → Auth controller: dispatches
- Auth controller → Resource, finding, scan models: queries
- Dashboard routes → Dashboard controller: dispatches
- Dashboard controller → Resource, finding, scan models: queries
- Scan routes → Scan controller: dispatches
- Scan controller → Scan engine: starts scan
- Background scheduler → Scan engine: triggers scan
- Scan engine → Resource, finding, scan models: reads and writes
- Resource, finding, scan models → MongoDB: persists data
- Scan engine → Provider scanners: dispatches
- Provider scanners → Cloud providers: discovers assets
- Scan engine → CIS rule registry: evaluates resources
- Scan engine → Posture calculator: calculates posture
- Scan engine → Alert mailer: dispatches alerts
- Alert mailer → SMTP service: sends email
- Report routes → PDF reports: dispatches
- PDF reports → Resource, finding, scan models: reads records
- PDF reports → Posture calculator: calculates posture
- AI routes → AI remediation: dispatches
- AI remediation → Resource, finding, scan models: loads finding
- AI remediation → Gemini API: requests remediation