# sundas-razzaq/infracracknet architecture

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

- Interactive diagram: https://gitdiagram.com/sundas-razzaq/infracracknet
- Repository: https://github.com/sundas-razzaq/infracracknet

## Overview

#### Purpose and topology
InfraCrackNet is a full-stack infrastructure-inspection system for detecting cracks in buildings, roads, and bridges with AI-assisted analysis. It has a Vite/React single-page frontend and a Node.js backend. The user workflow spans projects, inspections, image uploads, AI analysis, human validation/annotation, reporting, and notifications.

#### Application entry points
Frontend bootstraps from `Infra-frontend/src/main.jsx` into `Infra-frontend/src/App.jsx`; dashboard navigation is concentrated in `Infra-frontend/src/routes/DashboardRoutes.jsx`. Backend deployment/runtime entry points are `Infra-Backend/index.js`, `Infra-Backend/server.js`, and Express app composition in `Infra-Backend/src/app.js`.

#### Client application and access boundary
The React client separates public/auth/dashboard layouts and uses route protection plus shared authentication state. `Infra-frontend/src/components/ProtectedRoute.jsx`, `Infra-frontend/src/context/AuthContext.jsx`, and `Infra-frontend/src/layouts/DashboardLayout.jsx` form the primary client-side access and shell boundary. Feature-specific API modules call the backend, e.g. `Infra-frontend/src/api/analysisApi.js`, `Infra-frontend/src/api/inspectionApi.js`, and `Infra-frontend/src/api/reportApi.js`.

#### Core inspection domain
Projects contain or organize inspections; inspections carry uploaded images and lifecycle/status data. Backend persistence models define these aggregates in `Infra-Backend/src/models/project.js`, `Infra-Backend/src/models/inspection.js`, and `Infra-Backend/src/models/inspectionImage.js`. Their HTTP interfaces are handled by paired routes/controllers such as `Infra-Backend/src/routes/projectRoutes.js`, `Infra-Backend/src/controllers/inspectionControllers.js`, and `Infra-Backend/src/controllers/inspectionImageControllers.js`. The frontend implements create/edit, inspection execution, and image-upload experiences under `Infra-frontend/src/pages/dashboard/projects/` and `Infra-frontend/src/pages/dashboard/inspection/`.

#### Image ingestion and AI analysis pipeline
Inspection images pass through upload middleware and Cloudinary integration before analysis records/results are exposed. Key boundaries are `Infra-Backend/src/middleware/uploadMiddleware.js`, `Infra-Backend/src/config/cloudinary.js`, and `Infra-Backend/src/services/cloudinaryService.js`. Analysis orchestration is split between `Infra-Backend/src/controllers/analysisController.js`, `Infra-Backend/src/services/analysisService.js`, and persisted analysis/crack entities in `Infra-Backend/src/models/AIAnalysis.js` and `Infra-Backend/src/models/crackDetection.js`. The UI presents processing and result stages via `Infra-frontend/src/pages/dashboard/analysis/AIProcessingPage.jsx` and `Infra-frontend/src/pages/dashboard/analysis/AIResultsPage.jsx`.

#### Human review and validation
AI detections can be inspected, edited, rejected, or manually annotated before becoming trusted results. The backend annotation boundary is `Infra-Backend/src/routes/annotationRoutes.js` and `Infra-Backend/src/controllers/annotationController.js`; validation rules reside in `Infra-Backend/src/validations/annotationValidators.js`. The main review workspace is `Infra-frontend/src/pages/dashboard/annotation/AnnotationWorkspacePage.jsx`, supported by the interactive canvas and editing controls in `Infra-frontend/src/components/annotation/AnnotationCanvas.jsx` and `Infra-frontend/src/components/annotation/CrackEditorModal.jsx`.

#### Identity, roles, and notifications
Authentication, profile operations, and protected API authorization are implemented through `Infra-Backend/src/controllers/authControllers.js`, `Infra-Backend/src/services/authService.js`, `Infra-Backend/src/middleware/authMiddleware.js`, and `Infra-Backend/src/models/user.js`. Role-oriented dashboard views exist for inspectors and engineers at `Infra-frontend/src/pages/dashboard/inspectorDashboard.jsx` and `Infra-frontend/src/pages/dashboard/engineerDashboard.jsx`. Notifications are persisted and delivered through `Infra-Backend/src/models/notification.js`, `Infra-Backend/src/services/notificationService.js`, and likely email via `Infra-Backend/src/services/emailService.js`.

#### Reports and infrastructure
Validated inspection/analysis information feeds report records and PDF generation. `Infra-Backend/src/controllers/reportControllers.js`, `Infra-Backend/src/models/report.js`, and `Infra-Backend/src/pdf/generateReport.js` form that reporting path; frontend report browsing/export is under `Infra-frontend/src/pages/dashboard/reports/`. Material infrastructure includes database setup in `Infra-Backend/src/config/db.js`, Cloudinary for image storage, email delivery, and Vercel deployment descriptors at `Infra-Backend/vercel.json` and `Infra-frontend/vercel.json`.

Main entry points: [`Infra-Backend/src/app.js`](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/app.js) (Express application), [`Infra-Backend/src/config/db.js`](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/config/db.js) (Application database), [`Infra-frontend/src/components/ProtectedRoute.jsx`](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/components/ProtectedRoute.jsx) (Auth and protected shell), [`Infra-Backend/src/services/analysisService.js`](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/analysisService.js) (AI analysis orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_bootstrap["Client bootstrap<br/>Vite entry<br/>[main.jsx]"]
  node_client_routes["Dashboard routes<br/>React routing"]
  node_client_access["Auth and protected shell<br/>client access boundary<br/>[ProtectedRoute.jsx]"]
  node_client_workflows["Inspection workflows<br/>dashboard pages"]
  node_client_analysis["Analysis results UI<br/>dashboard pages<br/>[AIResultsPage.jsx]"]
  node_client_review["Annotation workspace<br/>review UI"]
  node_client_reports["Report UI<br/>dashboard pages"]
  node_api_clients["Feature API clients<br/>frontend API modules<br/>[analysisApi.js]"]
end

subgraph group_backend["Node/Express backend"]
  node_server["Express application<br/>HTTP API<br/>[app.js]"]
  node_identity["Identity and authorization<br/>auth service<br/>[authService.js]"]
  node_inspections["Projects and inspections<br/>domain API"]
  node_ingestion["Image ingestion<br/>upload pipeline"]
  node_analysis["AI analysis orchestration<br/>analysis service<br/>[analysisService.js]"]
  node_annotation["Human validation<br/>annotation API"]
  node_reporting["Reports and PDF generation<br/>reporting pipeline<br/>[generateReport.js]"]
  node_notifications["Notifications<br/>notification service"]
end

subgraph group_services["Infrastructure services"]
  node_database[("Application database<br/>[db.js]")]
  node_cloudinary[("Cloudinary<br/>image storage<br/>[cloudinary.js]")]
  node_email["Email delivery<br/>email service<br/>[emailService.js]"]
end

node_client_bootstrap -->|"mounts"| node_client_routes
node_client_routes -->|"applies guard and shell"| node_client_access
node_client_access -->|"hosts"| node_client_workflows
node_client_access -->|"hosts"| node_client_analysis
node_client_access -->|"hosts"| node_client_review
node_client_access -->|"hosts"| node_client_reports
node_client_workflows -->|"uses"| node_api_clients
node_client_analysis -->|"uses"| node_api_clients
node_client_review -->|"uses"| node_api_clients
node_client_reports -->|"uses"| node_api_clients
node_api_clients -->|"HTTP requests"| node_server
node_server -->|"auth endpoints and middleware"| node_identity
node_server -->|"inspection routes"| node_inspections
node_server -->|"analysis routes"| node_analysis
node_server -->|"annotation routes"| node_annotation
node_server -->|"report routes"| node_reporting
node_identity -->|"users and roles"| node_database
node_inspections -->|"uploads inspection images"| node_ingestion
node_inspections -->|"projects, inspections, images"| node_database
node_ingestion -->|"stores assets"| node_cloudinary
node_ingestion -->|"provides image assets"| node_analysis
node_analysis -->|"analysis and crack records"| node_database
node_analysis -->|"submits detections for review"| node_annotation
node_annotation -->|"persists validated findings"| node_database
node_annotation -->|"trusted findings"| node_reporting
node_reporting -->|"report records"| node_database
node_analysis -.->|"analysis status"| node_notifications
node_notifications -->|"persists notifications"| node_database
node_notifications -->|"sends email"| node_email

click node_client_bootstrap "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/main.jsx"
click node_client_routes "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/routes/DashboardRoutes.jsx"
click node_client_access "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/components/ProtectedRoute.jsx"
click node_client_analysis "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/pages/dashboard/analysis/AIResultsPage.jsx"
click node_client_review "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/pages/dashboard/annotation/AnnotationWorkspacePage.jsx"
click node_api_clients "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/api/analysisApi.js"
click node_server "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/app.js"
click node_identity "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/authService.js"
click node_inspections "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/controllers/inspectionControllers.js"
click node_ingestion "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/middleware/uploadMiddleware.js"
click node_analysis "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/analysisService.js"
click node_annotation "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/controllers/annotationController.js"
click node_reporting "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/pdf/generateReport.js"
click node_notifications "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/notificationService.js"
click node_database "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/config/db.js"
click node_cloudinary "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/config/cloudinary.js"
click node_email "https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/emailService.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_client_bootstrap,node_client_routes,node_client_access,node_client_workflows,node_client_analysis,node_client_review,node_client_reports,node_api_clients toneBlue
class node_server,node_identity,node_inspections,node_ingestion,node_analysis,node_annotation,node_reporting,node_notifications toneAmber
class node_database,node_cloudinary,node_email toneMint
```

## Components

### React client

- [Client bootstrap](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/main.jsx): Vite entry · `Infra-frontend/src/main.jsx`
- [Dashboard routes](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/routes/DashboardRoutes.jsx): React routing · Public, auth, and dashboard navigation. · `Infra-frontend/src/routes/DashboardRoutes.jsx`
- [Auth and protected shell](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/components/ProtectedRoute.jsx): client access boundary · Shared session state, route guard, and dashboard layout. · `Infra-frontend/src/components/ProtectedRoute.jsx`
- **Inspection workflows**: dashboard pages · Project editing, inspection execution, and image upload.
- [Analysis results UI](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/pages/dashboard/analysis/AIResultsPage.jsx): dashboard pages · Processing status and AI result presentation. · `Infra-frontend/src/pages/dashboard/analysis/AIResultsPage.jsx`
- [Annotation workspace](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/pages/dashboard/annotation/AnnotationWorkspacePage.jsx): review UI · Interactive detection validation and editing. · `Infra-frontend/src/pages/dashboard/annotation/AnnotationWorkspacePage.jsx`
- **Report UI**: dashboard pages · Report browsing and export.
- [Feature API clients](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-frontend/src/api/analysisApi.js): frontend API modules · Analysis, inspection, and report HTTP calls. · `Infra-frontend/src/api/analysisApi.js`

### Node/Express backend

- [Express application](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/app.js): HTTP API · Composes backend middleware and routes. · `Infra-Backend/src/app.js`
- [Identity and authorization](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/authService.js): auth service · Authentication, profiles, roles, and protected API access. · `Infra-Backend/src/services/authService.js`
- [Projects and inspections](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/controllers/inspectionControllers.js): domain API · Project, inspection, image, and lifecycle management. · `Infra-Backend/src/controllers/inspectionControllers.js`
- [Image ingestion](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/middleware/uploadMiddleware.js): upload pipeline · Upload middleware and Cloudinary asset handling. · `Infra-Backend/src/middleware/uploadMiddleware.js`
- [AI analysis orchestration](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/analysisService.js): analysis service · Creates analysis and crack-detection results. · `Infra-Backend/src/services/analysisService.js`
- [Human validation](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/controllers/annotationController.js): annotation API · Validates, edits, rejects, and annotates detections. · `Infra-Backend/src/controllers/annotationController.js`
- [Reports and PDF generation](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/pdf/generateReport.js): reporting pipeline · Builds report records and PDFs from trusted findings. · `Infra-Backend/src/pdf/generateReport.js`
- [Notifications](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/notificationService.js): notification service · Persists notifications and triggers email delivery. · `Infra-Backend/src/services/notificationService.js`

### Infrastructure services

- [Application database](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/config/db.js): database · Stores users, projects, inspections, analyses, findings, reports, and notifications. · `Infra-Backend/src/config/db.js`
- [Cloudinary](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/config/cloudinary.js): image storage · External inspection-image storage. · `Infra-Backend/src/config/cloudinary.js`
- [Email delivery](https://github.com/sundas-razzaq/infracracknet/blob/main/Infra-Backend/src/services/emailService.js): email service · Outbound notification delivery. · `Infra-Backend/src/services/emailService.js`

## Connections

- Client bootstrap → Dashboard routes: mounts
- Dashboard routes → Auth and protected shell: applies guard and shell
- Auth and protected shell → Inspection workflows: hosts
- Auth and protected shell → Analysis results UI: hosts
- Auth and protected shell → Annotation workspace: hosts
- Auth and protected shell → Report UI: hosts
- Inspection workflows → Feature API clients: uses
- Analysis results UI → Feature API clients: uses
- Annotation workspace → Feature API clients: uses
- Report UI → Feature API clients: uses
- Feature API clients → Express application: HTTP requests
- Express application → Identity and authorization: auth endpoints and middleware
- Express application → Projects and inspections: inspection routes
- Express application → AI analysis orchestration: analysis routes
- Express application → Human validation: annotation routes
- Express application → Reports and PDF generation: report routes
- Identity and authorization → Application database: users and roles
- Projects and inspections → Image ingestion: uploads inspection images
- Projects and inspections → Application database: projects, inspections, images
- Image ingestion → Cloudinary: stores assets
- Image ingestion → AI analysis orchestration: provides image assets
- AI analysis orchestration → Application database: analysis and crack records
- AI analysis orchestration → Human validation: submits detections for review
- Human validation → Application database: persists validated findings
- Human validation → Reports and PDF generation: trusted findings
- Reports and PDF generation → Application database: report records
- AI analysis orchestration → Notifications: analysis status
- Notifications → Application database: persists notifications
- Notifications → Email delivery: sends email
