# hky0826/fyp-smart-campus architecture

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

- Interactive diagram: https://gitdiagram.com/hky0826/fyp-smart-campus
- Repository: https://github.com/hky0826/fyp-smart-campus

## Overview

This repository combines campus access control, a cloud RAG assistant, dashboard services, and mapping/navigation with notifications. A kiosk captures a face, verifies access locally, and synchronizes device data with the cloud; users can also ask audio or text questions. Administrators manage campus data and maps, while navigation computes routes and can trigger notifications. The graph focuses on those product workflows and the RAG ingestion/retrieval and mapping-analysis layers. Some subsystem wiring is documented or indexed rather than shown in excerpts, so uncertain links are omitted or dashed.

Main entry points: [`access_control/facial_recognition/src/api/main.py`](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/api/main.py) (Kiosk API), [`access_control/ui/access_control_gui/controllers/access_controller.py`](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/access_controller.py) (Kiosk Controller), [`cloud/RagChatbot/services/chat_service.py`](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/services/chat_service.py) (Chat Service), [`access_control/ui/access_control_gui/controllers/chatbot_controller.py`](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/chatbot_controller.py) (Audio Chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Edge Access"]
  node_edge_api["Kiosk API<br/>[main.py]"]
  node_face_pipeline["Face Access Pipeline<br/>[access_control.py]"]
  node_device_db[("Device SQLite<br/>[database.py]")]
  node_edge_sync["Device Sync<br/>[sync.py]"]
  node_kiosk_ui["Kiosk Controller"]
  node_kiosk_api_client["Kiosk API Client<br/>[api_client.py]"]
  node_camera["Camera Controller"]
  node_audio_chat["Audio Chat"]
  node_edge_audio["Audio Terminal<br/>[main.py]"]
end

subgraph group_cloud["Cloud Assistant"]
  node_rag_router["RAG API Router<br/>[router.py]"]
  node_chat_service["Chat Service<br/>[chat_service.py]"]
  node_query_router["Query Classification<br/>[query_router.py]"]
  node_retriever["Document Retrieval<br/>[retriever.py]"]
  node_vector_store[("Vector Store<br/>[vector_store.py]")]
  node_llm["LLM Generation"]
  node_ingestion["Document Ingestion"]
  node_embedding["Embedding Service"]
end

subgraph group_dashboard["Campus Dashboard"]
  node_cloud_api["Cloud Dashboard API<br/>[main.py]"]
  node_campus_db[("Campus Database<br/>[database.py]")]
  node_admin_ui["Dashboard Frontend<br/>[App.jsx]"]
end

subgraph group_mapping["Mapping Navigation"]
  node_map_ui["Map Editor UI<br/>[App.js]"]
  node_map_backend["Map Controller<br/>[mapController.js]"]
  node_ai_analysis["Floorplan Analysis"]
  node_nav_engine["Navigation Engine"]
  node_notification["Notification Worker<br/>[consumer.js]"]
end

subgraph group_surveillance["Surveillance"]
  node_surveillance_pipeline["Surveillance Pipeline<br/>[pipeline.py]"]
  node_surveillance_db[("Surveillance SQLite<br/>[database.py]")]
end

node_visitor(("Kiosk User"))
node_operator(("Campus Admin"))

node_visitor -->|"uses kiosk"| node_kiosk_ui
node_kiosk_ui -->|"requests access"| node_kiosk_api_client
node_kiosk_ui -->|"reads camera"| node_camera
node_kiosk_ui -->|"controls chat"| node_audio_chat
node_audio_chat -->|"requests audio chat"| node_kiosk_api_client
node_audio_chat -->|"plays audio"| node_edge_audio
node_kiosk_api_client -.->|"calls kiosk API"| node_edge_api
node_edge_api -->|"dispatches access checks"| node_face_pipeline
node_edge_api -->|"starts synchronization"| node_edge_sync
node_edge_api -->|"checks database status"| node_device_db
node_edge_sync -.->|"syncs device data"| node_cloud_api
node_operator -->|"manages campus"| node_admin_ui
node_admin_ui -.->|"uses dashboard session"| node_cloud_api
node_cloud_api -->|"uses database"| node_campus_db
node_visitor -.->|"asks questions"| node_rag_router
node_rag_router -.->|"routes chat"| node_chat_service
node_chat_service -.->|"classifies query"| node_query_router
node_chat_service -.->|"retrieves context"| node_retriever
node_retriever -.->|"searches vectors"| node_vector_store
node_chat_service -.->|"generates answer"| node_llm
node_operator -.->|"ingests documents"| node_ingestion
node_ingestion -->|"creates embeddings"| node_embedding
node_ingestion -->|"stores vectors"| node_vector_store
node_operator -->|"edits campus maps"| node_map_ui
node_map_ui -.->|"calls map API"| node_map_backend
node_map_backend -->|"requests analysis"| node_ai_analysis
node_operator -.->|"requests navigation"| node_nav_engine
node_nav_engine -->|"triggers notifications"| node_notification
node_surveillance_pipeline -->|"loads templates"| node_surveillance_db

click node_edge_api "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/api/main.py"
click node_face_pipeline "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/pipelines/access_control.py"
click node_device_db "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/face/database.py"
click node_edge_sync "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/sync.py"
click node_kiosk_ui "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/access_controller.py"
click node_kiosk_api_client "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/api_client.py"
click node_camera "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/camera_controller.py"
click node_audio_chat "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/chatbot_controller.py"
click node_edge_audio "https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/audio_io/main.py"
click node_cloud_api "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/dashboard/backend/app/main.py"
click node_campus_db "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/dashboard/backend/app/core/database.py"
click node_admin_ui "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/dashboard/frontend/src/App.jsx"
click node_rag_router "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/router.py"
click node_chat_service "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/services/chat_service.py"
click node_query_router "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/generation/query_router.py"
click node_retriever "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/retrieval/retriever.py"
click node_vector_store "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/retrieval/vector_store.py"
click node_llm "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/generation/google_llm_service.py"
click node_ingestion "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/services/ingestion_service.py"
click node_embedding "https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/embeddings/google_embedding_service.py"
click node_map_ui "https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/frontend/src/App.js"
click node_map_backend "https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/backend/controllers/mapController.js"
click node_ai_analysis "https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/ai-services/src/services/floorplan_analyzer.py"
click node_nav_engine "https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/backend/controllers/engineController.js"
click node_notification "https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/backend/consumer.js"
click node_surveillance_pipeline "https://github.com/hky0826/fyp-smart-campus/blob/main/surveillance/pipeline.py"
click node_surveillance_db "https://github.com/hky0826/fyp-smart-campus/blob/main/surveillance/database.py"

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_edge_api,node_face_pipeline,node_device_db,node_edge_sync,node_kiosk_ui,node_kiosk_api_client,node_camera,node_audio_chat,node_edge_audio,node_visitor toneBlue
class node_rag_router,node_chat_service,node_query_router,node_retriever,node_vector_store,node_llm,node_ingestion,node_embedding toneAmber
class node_cloud_api,node_campus_db,node_admin_ui toneMint
class node_map_ui,node_map_backend,node_ai_analysis,node_nav_engine,node_notification toneRose
class node_surveillance_pipeline,node_surveillance_db,node_operator toneIndigo
```

## Components

### Edge Access

- [Kiosk API](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/api/main.py): `access_control/facial_recognition/src/api/main.py`
- [Face Access Pipeline](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/pipelines/access_control.py): `access_control/facial_recognition/src/pipelines/access_control.py`
- [Device SQLite](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/face/database.py): `access_control/facial_recognition/src/face/database.py`
- [Device Sync](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/facial_recognition/src/sync.py): `access_control/facial_recognition/src/sync.py`
- [Kiosk Controller](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/access_controller.py): `access_control/ui/access_control_gui/controllers/access_controller.py`
- [Kiosk API Client](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/api_client.py): `access_control/ui/access_control_gui/controllers/api_client.py`
- [Camera Controller](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/camera_controller.py): `access_control/ui/access_control_gui/controllers/camera_controller.py`
- [Audio Chat](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/ui/access_control_gui/controllers/chatbot_controller.py): `access_control/ui/access_control_gui/controllers/chatbot_controller.py`
- [Audio Terminal](https://github.com/hky0826/fyp-smart-campus/blob/main/access_control/audio_io/main.py): `access_control/audio_io/main.py`

### Cloud Assistant

- [RAG API Router](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/router.py): `cloud/RagChatbot/router.py`
- [Chat Service](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/services/chat_service.py): `cloud/RagChatbot/services/chat_service.py`
- [Query Classification](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/generation/query_router.py): `cloud/RagChatbot/generation/query_router.py`
- [Document Retrieval](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/retrieval/retriever.py): `cloud/RagChatbot/retrieval/retriever.py`
- [Vector Store](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/retrieval/vector_store.py): `cloud/RagChatbot/retrieval/vector_store.py`
- [LLM Generation](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/generation/google_llm_service.py): `cloud/RagChatbot/generation/google_llm_service.py`
- [Document Ingestion](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/services/ingestion_service.py): `cloud/RagChatbot/services/ingestion_service.py`
- [Embedding Service](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/RagChatbot/embeddings/google_embedding_service.py): `cloud/RagChatbot/embeddings/google_embedding_service.py`

### Campus Dashboard

- [Cloud Dashboard API](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/dashboard/backend/app/main.py): `cloud/dashboard/backend/app/main.py`
- [Campus Database](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/dashboard/backend/app/core/database.py): `cloud/dashboard/backend/app/core/database.py`
- [Dashboard Frontend](https://github.com/hky0826/fyp-smart-campus/blob/main/cloud/dashboard/frontend/src/App.jsx): `cloud/dashboard/frontend/src/App.jsx`

### Mapping Navigation

- [Map Editor UI](https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/frontend/src/App.js): `mapping_and_notification/frontend/src/App.js`
- [Map Controller](https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/backend/controllers/mapController.js): `mapping_and_notification/backend/controllers/mapController.js`
- [Floorplan Analysis](https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/ai-services/src/services/floorplan_analyzer.py): `mapping_and_notification/ai-services/src/services/floorplan_analyzer.py`
- [Navigation Engine](https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/backend/controllers/engineController.js): `mapping_and_notification/backend/controllers/engineController.js`
- [Notification Worker](https://github.com/hky0826/fyp-smart-campus/blob/main/mapping_and_notification/backend/consumer.js): `mapping_and_notification/backend/consumer.js`

### Surveillance

- [Surveillance Pipeline](https://github.com/hky0826/fyp-smart-campus/blob/main/surveillance/pipeline.py): `surveillance/pipeline.py`
- [Surveillance SQLite](https://github.com/hky0826/fyp-smart-campus/blob/main/surveillance/database.py): `surveillance/database.py`

### Other components

- **Kiosk User**
- **Campus Admin**

## Connections

- Kiosk User → Kiosk Controller: uses kiosk (evidence: `README.md`)
- Kiosk Controller → Kiosk API Client: requests access (evidence: `access_control/ui/access_control_gui/controllers/access_controller.py`)
- Kiosk Controller → Camera Controller: reads camera (evidence: `access_control/ui/access_control_gui/controllers/access_controller.py`)
- Kiosk Controller → Audio Chat: controls chat (evidence: `access_control/ui/access_control_gui/controllers/access_controller.py`)
- Audio Chat → Kiosk API Client: requests audio chat (evidence: `access_control/ui/access_control_gui/controllers/chatbot_controller.py`)
- Audio Chat → Audio Terminal: plays audio (evidence: `access_control/ui/access_control_gui/controllers/chatbot_controller.py`)
- Kiosk API Client → Kiosk API: calls kiosk API
- Kiosk API → Face Access Pipeline: dispatches access checks (evidence: `access_control/facial_recognition/src/api/main.py`)
- Kiosk API → Device Sync: starts synchronization (evidence: `access_control/facial_recognition/src/api/main.py`)
- Kiosk API → Device SQLite: checks database status (evidence: `access_control/facial_recognition/src/api/main.py`)
- Device Sync → Cloud Dashboard API: syncs device data (evidence: `README.md`)
- Campus Admin → Dashboard Frontend: manages campus (evidence: `README.md`)
- Dashboard Frontend → Cloud Dashboard API: uses dashboard session (evidence: `README.md`)
- Cloud Dashboard API → Campus Database: uses database
- Kiosk User → RAG API Router: asks questions
- RAG API Router → Chat Service: routes chat
- Chat Service → Query Classification: classifies query
- Chat Service → Document Retrieval: retrieves context
- Document Retrieval → Vector Store: searches vectors
- Chat Service → LLM Generation: generates answer
- Campus Admin → Document Ingestion: ingests documents
- Document Ingestion → Embedding Service: creates embeddings (evidence: `cloud/RagChatbot/services/ingestion_service.py`)
- Document Ingestion → Vector Store: stores vectors (evidence: `cloud/RagChatbot/services/ingestion_service.py`)
- Campus Admin → Map Editor UI: edits campus maps (evidence: `README.md`)
- Map Editor UI → Map Controller: calls map API
- Map Controller → Floorplan Analysis: requests analysis (evidence: `mapping_and_notification/backend/controllers/mapController.js`)
- Campus Admin → Navigation Engine: requests navigation
- Navigation Engine → Notification Worker: triggers notifications (evidence: `mapping_and_notification/backend/controllers/engineController.js`)
- Surveillance Pipeline → Surveillance SQLite: loads templates (evidence: `surveillance/pipeline.py`)