# danhdct122c3/smart_campus architecture

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

- Interactive diagram: https://gitdiagram.com/danhdct122c3/smart_campus
- Repository: https://github.com/danhdct122c3/smart_campus

## Overview

#### Purpose and Entry Points
This is a Smart Campus/employee-management platform: a React single-page frontend backed by a Python API designed for AWS Lambda, with attendance/face recognition, workforce workflows, notifications, analytics, security, and AI assistance. Frontend bootstraps at `frontend/src/main.jsx` and routes through `frontend/src/App.jsx`. Backend application assembly is in `backend/app/main.py`; Lambda invocation is adapted by `backend/app/handler.py`.

#### API Composition and Runtime Boundary
The backend is a modular Python API. `backend/app/api/router.py` is the central route aggregation boundary; each business module exposes a router and separates request schemas, service logic, and (where needed) repository access. Shared configuration, exception handling, and response conventions live in `backend/app/core/config.py`, `backend/app/core/exceptions.py`, and `backend/app/core/responses.py`. Environment values are represented by `backend/.env.example`.

#### Identity, Users, and Access Control
Authentication and user lifecycle are centered in `backend/app/modules/auth/router.py`, `backend/app/modules/auth/service.py`, and `backend/app/modules/users/service.py`. The frontend retains session/auth state in `frontend/src/context/AuthContext.jsx` and enforces UI access through `frontend/src/components/ProtectedRoute.jsx`. AWS Cognito setup is represented by `aws-image/setupCognito`; IAM provisioning is represented by `aws-image/setupIAM`.

#### Attendance and Biometric Flow
Attendance processing combines API handling, persistence, and policy evaluation: `backend/app/modules/attendance/router.py`, `backend/app/modules/attendance/service.py`, and `backend/app/modules/attendance/rule_engine.py`. Face enrollment/recognition is isolated in `backend/app/modules/faces/service.py` and its repository. These modules cross the AWS service boundary through `backend/app/shared/aws/rekognition.py`, with deployment provisioning indicated by `aws-image/setupRekognition`.

#### Operational Domain Modules
Employee-facing workflow APIs are organized by bounded domain: leave requests in `backend/app/modules/leaves/service.py`, task management in `backend/app/modules/tasks/service.py`, and notification delivery/state in `backend/app/modules/notifications/service.py`. Administration/security controls are handled by `backend/app/modules/security/service.py` and `backend/app/modules/security/settings_repo.py`. The corresponding SPA pages are `frontend/src/pages/Leaves.jsx`, `frontend/src/pages/Tasks.jsx`, and `frontend/src/pages/Notifications.jsx`.

#### Asynchronous Events, Notifications, and Analytics
Workers separate non-request processing from API execution: `backend/app/workers/notification_worker.py`, `backend/app/workers/analytics_worker.py`, and `backend/app/workers/security_worker.py`. Event and messaging integrations are encapsulated in `backend/app/shared/aws/eventbridge.py` and `backend/app/shared/aws/sns.py`; infrastructure folders also indicate EventBridge, SQS, SES, and CloudWatch usage (`aws-image/setupEvenBridge`, `aws-image/setupSQS`, `aws-image/setupSES`, `aws-image/setupCloudWatch`). Reporting services/repositories in `backend/app/modules/reports/service.py` and `backend/app/modules/reports/repository.py` likely consume Athena through `backend/app/shared/aws/athena.py`.

#### AI, Data, and AWS Deployment Surface
The AI assistant API is implemented in `backend/app/modules/ai_assistant/service.py` and reaches Amazon Bedrock via `backend/app/shared/aws/bedrock.py`; its client page is `frontend/src/pages/AIAssistant.jsx`. Persistence and object storage adapters are `backend/app/shared/aws/dynamodb.py` and `backend/app/shared/aws/s3.py`, with AWS setup coverage for DB, S3, Lambda, API, CloudFront, WAF, X-Ray, and CodePipeline under `aws-image/`. CI build entry points are `buildspec-backend.yml` and `buildspec-frontend.yml`.

Main entry points: [`backend/app/api/router.py`](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/api/router.py) (Route Aggregation), [`frontend/src/main.jsx`](https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/main.jsx) (SPA Bootstrap & Routes), [`backend/app/modules/attendance/service.py`](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/attendance/service.py) (Attendance Policy), [`backend/app/modules/leaves/service.py`](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/leaves/service.py) (Workforce Workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React SPA"]
  node_spa_bootstrap["SPA Bootstrap &amp; Routes<br/>React entry<br/>[main.jsx]"]
  node_auth_ui["Auth State &amp; Route Guard<br/>React context<br/>[AuthContext.jsx]"]
  node_workflow_pages["Workflow Pages<br/>React pages<br/>[Leaves.jsx]"]
  node_ai_page["AI Assistant Page<br/>React page<br/>[AIAssistant.jsx]"]
end

subgraph group_api["Python API"]
  node_lambda_handler{{"Lambda Adapter<br/>Lambda handler<br/>[handler.py]"}}
  node_app["Application Assembly<br/>Python API app<br/>[main.py]"]
  node_api_router["Route Aggregation<br/>API router<br/>[router.py]"]
  node_identity["Identity &amp; Users<br/>domain services<br/>[service.py]"]
  node_attendance["Attendance Policy<br/>domain service<br/>[service.py]"]
  node_faces["Face Recognition<br/>domain service<br/>[service.py]"]
  node_workforce["Workforce Workflows<br/>domain services<br/>[service.py]"]
  node_reports["Reporting<br/>service and repository<br/>[service.py]"]
  node_ai_service["AI Assistant<br/>domain service<br/>[service.py]"]
end

subgraph group_async["Async Processing"]
  node_workers["Event Workers<br/>background workers"]
  node_eventing["Events &amp; Messaging<br/>AWS adapters<br/>[eventbridge.py]"]
end

subgraph group_aws["AWS Platform"]
  node_cognito{{"Cognito &amp; IAM<br/>identity infrastructure"}}
  node_rekognition{{"Amazon Rekognition<br/>biometric service<br/>[rekognition.py]"}}
  node_data_storage[("DynamoDB &amp; S3<br/>storage adapters<br/>[dynamodb.py]")]
  node_athena[("Amazon Athena<br/>analytics adapter<br/>[athena.py]")]
  node_bedrock{{"Amazon Bedrock<br/>AI adapter<br/>[bedrock.py]"}}
  node_delivery["Build &amp; Deployment<br/>CodeBuild pipeline"]
end

node_spa_bootstrap -->|"provides session"| node_auth_ui
node_spa_bootstrap -->|"routes to"| node_workflow_pages
node_spa_bootstrap -->|"routes to"| node_ai_page
node_auth_ui -->|"authenticated API calls"| node_api_router
node_workflow_pages -->|"workflow API calls"| node_api_router
node_ai_page -->|"assistant requests"| node_api_router
node_lambda_handler -->|"invokes"| node_app
node_app -->|"mounts"| node_api_router
node_api_router -->|"auth and users"| node_identity
node_api_router -->|"attendance endpoints"| node_attendance
node_api_router -->|"workflow endpoints"| node_workforce
node_api_router -->|"report endpoints"| node_reports
node_api_router -->|"assistant endpoint"| node_ai_service
node_identity -->|"identity integration"| node_cognito
node_attendance -->|"uses recognition"| node_faces
node_faces -->|"recognizes faces"| node_rekognition
node_attendance -->|"persists records"| node_data_storage
node_workforce -->|"persists workflow state"| node_data_storage
node_workforce -->|"publishes events"| node_eventing
node_eventing -->|"triggers async work"| node_workers
node_workers -->|"reads and updates state"| node_data_storage
node_workers -->|"processes analytics"| node_athena
node_reports -->|"queries analytics"| node_athena
node_ai_service -->|"generates responses"| node_bedrock
node_delivery -.->|"builds frontend"| node_spa_bootstrap
node_delivery -.->|"deploys backend"| node_lambda_handler

click node_spa_bootstrap "https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/main.jsx"
click node_auth_ui "https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/context/AuthContext.jsx"
click node_workflow_pages "https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/pages/Leaves.jsx"
click node_ai_page "https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/pages/AIAssistant.jsx"
click node_lambda_handler "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/handler.py"
click node_app "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/main.py"
click node_api_router "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/api/router.py"
click node_identity "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/auth/service.py"
click node_attendance "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/attendance/service.py"
click node_faces "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/faces/service.py"
click node_workforce "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/leaves/service.py"
click node_reports "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/reports/service.py"
click node_ai_service "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/ai_assistant/service.py"
click node_workers "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/workers/notification_worker.py"
click node_eventing "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/eventbridge.py"
click node_cognito "https://github.com/danhdct122c3/smart_campus/tree/main/aws-image/setupCognito"
click node_rekognition "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/rekognition.py"
click node_data_storage "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/dynamodb.py"
click node_athena "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/athena.py"
click node_bedrock "https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/bedrock.py"
click node_delivery "https://github.com/danhdct122c3/smart_campus/blob/main/buildspec-backend.yml"

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_spa_bootstrap,node_auth_ui,node_workflow_pages,node_ai_page toneBlue
class node_lambda_handler,node_app,node_api_router,node_identity,node_attendance,node_faces,node_workforce,node_reports,node_ai_service toneAmber
class node_workers,node_eventing toneMint
class node_cognito,node_rekognition,node_data_storage,node_athena,node_bedrock,node_delivery toneRose
```

## Components

### React SPA

- [SPA Bootstrap & Routes](https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/main.jsx): React entry · `frontend/src/main.jsx`
- [Auth State & Route Guard](https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/context/AuthContext.jsx): React context · `frontend/src/context/AuthContext.jsx`
- [Workflow Pages](https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/pages/Leaves.jsx): React pages · Leave, task, and notification user workflows. · `frontend/src/pages/Leaves.jsx`
- [AI Assistant Page](https://github.com/danhdct122c3/smart_campus/blob/main/frontend/src/pages/AIAssistant.jsx): React page · `frontend/src/pages/AIAssistant.jsx`

### Python API

- [Lambda Adapter](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/handler.py): Lambda handler · `backend/app/handler.py`
- [Application Assembly](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/main.py): Python API app · `backend/app/main.py`
- [Route Aggregation](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/api/router.py): API router · `backend/app/api/router.py`
- [Identity & Users](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/auth/service.py): domain services · Authentication, lifecycle, and access control. · `backend/app/modules/auth/service.py`
- [Attendance Policy](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/attendance/service.py): domain service · Attendance processing and rule evaluation. · `backend/app/modules/attendance/service.py`
- [Face Recognition](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/faces/service.py): domain service · Enrollment and recognition with repository access. · `backend/app/modules/faces/service.py`
- [Workforce Workflows](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/leaves/service.py): domain services · Leave, tasks, notifications, and security administration. · `backend/app/modules/leaves/service.py`
- [Reporting](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/reports/service.py): service and repository · `backend/app/modules/reports/service.py`
- [AI Assistant](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/modules/ai_assistant/service.py): domain service · `backend/app/modules/ai_assistant/service.py`

### Async Processing

- [Event Workers](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/workers/notification_worker.py): background workers · Notification, analytics, and security processing. · `backend/app/workers/notification_worker.py`
- [Events & Messaging](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/eventbridge.py): AWS adapters · EventBridge and SNS integration boundary. · `backend/app/shared/aws/eventbridge.py`

### AWS Platform

- [Cognito & IAM](https://github.com/danhdct122c3/smart_campus/tree/main/aws-image/setupCognito): identity infrastructure · `aws-image/setupCognito`
- [Amazon Rekognition](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/rekognition.py): biometric service · `backend/app/shared/aws/rekognition.py`
- [DynamoDB & S3](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/dynamodb.py): storage adapters · `backend/app/shared/aws/dynamodb.py`
- [Amazon Athena](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/athena.py): analytics adapter · `backend/app/shared/aws/athena.py`
- [Amazon Bedrock](https://github.com/danhdct122c3/smart_campus/blob/main/backend/app/shared/aws/bedrock.py): AI adapter · `backend/app/shared/aws/bedrock.py`
- [Build & Deployment](https://github.com/danhdct122c3/smart_campus/blob/main/buildspec-backend.yml): CodeBuild pipeline · Backend and frontend build specifications feed AWS deployment. · `buildspec-backend.yml`

## Connections

- SPA Bootstrap & Routes → Auth State & Route Guard: provides session
- SPA Bootstrap & Routes → Workflow Pages: routes to
- SPA Bootstrap & Routes → AI Assistant Page: routes to
- Auth State & Route Guard → Route Aggregation: authenticated API calls
- Workflow Pages → Route Aggregation: workflow API calls
- AI Assistant Page → Route Aggregation: assistant requests
- Lambda Adapter → Application Assembly: invokes
- Application Assembly → Route Aggregation: mounts
- Route Aggregation → Identity & Users: auth and users
- Route Aggregation → Attendance Policy: attendance endpoints
- Route Aggregation → Workforce Workflows: workflow endpoints
- Route Aggregation → Reporting: report endpoints
- Route Aggregation → AI Assistant: assistant endpoint
- Identity & Users → Cognito & IAM: identity integration
- Attendance Policy → Face Recognition: uses recognition
- Face Recognition → Amazon Rekognition: recognizes faces
- Attendance Policy → DynamoDB & S3: persists records
- Workforce Workflows → DynamoDB & S3: persists workflow state
- Workforce Workflows → Events & Messaging: publishes events
- Events & Messaging → Event Workers: triggers async work
- Event Workers → DynamoDB & S3: reads and updates state
- Event Workers → Amazon Athena: processes analytics
- Reporting → Amazon Athena: queries analytics
- AI Assistant → Amazon Bedrock: generates responses
- Build & Deployment → SPA Bootstrap & Routes: builds frontend
- Build & Deployment → Lambda Adapter: deploys backend