# momakkawi/agentic_tracking_system architecture

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

- Interactive diagram: https://gitdiagram.com/momakkawi/agentic_tracking_system
- Repository: https://github.com/momakkawi/agentic_tracking_system

## Overview

Agentic Tracking System turns badge and attendance data into operational views and AI-generated intelligence. The main user workflow runs from the dashboard through the REST API to attendance, alert, group, and agent services; agent workflows can ingest and preprocess data, validate it, identify cohorts, and produce insights or answer natural-language questions. Shared utilities provide repositories, configuration, mappings, and model wrappers, while memory supports session-isolated conversational context. The README documents the broad service and agent relationships; sampled source confirms selected API, dashboard, memory, and utility details, but not every runtime call.

Main entry points: [`agents/orchestrator/src/orchestrator/agent.py`](https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/orchestrator/src/orchestrator/agent.py) (Orchestrator), [`api/main.py`](https://github.com/momakkawi/agentic_tracking_system/blob/main/api/main.py) (FastAPI App), [`dashboard/src/App.jsx`](https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/App.jsx) (Dashboard), [`utils/src/utils/storage/factory.py`](https://github.com/momakkawi/agentic_tracking_system/blob/main/utils/src/utils/storage/factory.py) (File Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_dashboard["Dashboard<br/>[App.jsx]"]
  node_attendance_view["Attendance View<br/>[index.jsx]"]
  node_alerts_view["Alerts View<br/>[index.jsx]"]
  node_groups_view["Groups View<br/>[index.jsx]"]
  node_agent_view["Agent Chat<br/>[index.jsx]"]
  node_dashboard_api["API Client<br/>[api.js]"]
end

subgraph group_backend["API Backend"]
  node_api["FastAPI App<br/>[main.py]"]
  node_api_routes["REST Routes<br/>[attendance.py]"]
  node_session_service["Session Service<br/>[session_service.py]"]
  node_alert_service["Alert Service<br/>[alert_service.py]"]
  node_chat_service["Chat Service<br/>[chat_service.py]"]
  node_scheduler["Event Scheduler"]
end

subgraph group_agents["Agent Workflows"]
  node_orchestrator["Orchestrator<br/>[agent.py]"]
  node_memory[("Conversation Memory<br/>[short_term.py]")]
  node_pipeline["Data Pipeline<br/>[processor.py]"]
  node_validation["Data Validation<br/>[device_session.py]"]
  node_clustering["Cohort Clustering<br/>[louvain.py]"]
  node_insights["Knowledge Insights<br/>[data_insighter.py]"]
end

subgraph group_shared["Shared Services"]
  node_storage[("File Repositories<br/>[factory.py]")]
  node_config["Hot-Reload Config<br/>[config.py]"]
  node_model_wrappers["AI Model Wrappers<br/>[gemini.py]"]
end

node_admin(("Administrator"))

node_admin -->|"uses"| node_dashboard
node_dashboard -->|"routes to"| node_attendance_view
node_dashboard -->|"routes to"| node_alerts_view
node_dashboard -->|"routes to"| node_groups_view
node_dashboard -->|"routes to"| node_agent_view
node_dashboard -->|"uses"| node_dashboard_api
node_dashboard_api -->|"HTTP requests"| node_api
node_api -->|"registers"| node_api_routes
node_api -->|"dispatches"| node_orchestrator
node_api -->|"provides services"| node_session_service
node_api -->|"provides services"| node_alert_service
node_api -->|"provides services"| node_chat_service
node_api -->|"provides services"| node_scheduler
node_session_service -->|"reads sessions"| node_storage
node_alert_service -->|"reads alerts"| node_storage
node_chat_service -->|"persists chats"| node_storage
node_scheduler -->|"triggers workflows"| node_orchestrator
node_orchestrator -->|"consults"| node_memory
node_orchestrator -->|"coordinates"| node_pipeline
node_orchestrator -->|"coordinates"| node_validation
node_orchestrator -->|"coordinates"| node_clustering
node_orchestrator -->|"coordinates"| node_insights
node_pipeline -->|"uses repositories"| node_storage
node_orchestrator -->|"uses"| node_config
node_orchestrator -.->|"uses"| node_model_wrappers

click node_dashboard "https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/App.jsx"
click node_attendance_view "https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Attendance/index.jsx"
click node_alerts_view "https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Alerts/index.jsx"
click node_groups_view "https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Groups/index.jsx"
click node_agent_view "https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Agent/index.jsx"
click node_dashboard_api "https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/services/api.js"
click node_api "https://github.com/momakkawi/agentic_tracking_system/blob/main/api/main.py"
click node_api_routes "https://github.com/momakkawi/agentic_tracking_system/blob/main/api/routers/attendance.py"
click node_session_service "https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/session_service.py"
click node_alert_service "https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/alert_service.py"
click node_chat_service "https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/chat_service.py"
click node_scheduler "https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/scheduler_service.py"
click node_orchestrator "https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/orchestrator/src/orchestrator/agent.py"
click node_memory "https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/memory/short_term.py"
click node_pipeline "https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/data_pipeline/src/data_pipeline/pipelines/processor.py"
click node_validation "https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/data_validation/src/data_validation/validators/device_session.py"
click node_clustering "https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/group_identification/src/group_identification/identifier/louvain.py"
click node_insights "https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/knowledge_insight/src/knowledge_insight/core/data_insighter.py"
click node_storage "https://github.com/momakkawi/agentic_tracking_system/blob/main/utils/src/utils/storage/factory.py"
click node_config "https://github.com/momakkawi/agentic_tracking_system/blob/main/utils/src/utils/config.py"
click node_model_wrappers "https://github.com/momakkawi/agentic_tracking_system/blob/main/utils/src/utils/models/gemini.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_dashboard,node_attendance_view,node_alerts_view,node_groups_view,node_agent_view,node_dashboard_api toneBlue
class node_api,node_api_routes,node_session_service,node_alert_service,node_chat_service,node_scheduler toneAmber
class node_orchestrator,node_memory,node_pipeline,node_validation,node_clustering,node_insights toneMint
class node_storage,node_config,node_model_wrappers toneRose
class node_admin toneIndigo
```

## Components

### User Interface

- [Dashboard](https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/App.jsx): `dashboard/src/App.jsx`
- [Attendance View](https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Attendance/index.jsx): `dashboard/src/pages/Attendance/index.jsx`
- [Alerts View](https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Alerts/index.jsx): `dashboard/src/pages/Alerts/index.jsx`
- [Groups View](https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Groups/index.jsx): `dashboard/src/pages/Groups/index.jsx`
- [Agent Chat](https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/pages/Agent/index.jsx): `dashboard/src/pages/Agent/index.jsx`
- [API Client](https://github.com/momakkawi/agentic_tracking_system/blob/main/dashboard/src/services/api.js): `dashboard/src/services/api.js`

### API Backend

- [FastAPI App](https://github.com/momakkawi/agentic_tracking_system/blob/main/api/main.py): `api/main.py`
- [REST Routes](https://github.com/momakkawi/agentic_tracking_system/blob/main/api/routers/attendance.py): `api/routers/attendance.py`
- [Session Service](https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/session_service.py): `api/services/session_service.py`
- [Alert Service](https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/alert_service.py): `api/services/alert_service.py`
- [Chat Service](https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/chat_service.py): `api/services/chat_service.py`
- [Event Scheduler](https://github.com/momakkawi/agentic_tracking_system/blob/main/api/services/scheduler_service.py): `api/services/scheduler_service.py`

### Agent Workflows

- [Orchestrator](https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/orchestrator/src/orchestrator/agent.py): `agents/orchestrator/src/orchestrator/agent.py`
- [Conversation Memory](https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/memory/short_term.py): `agents/memory/short_term.py`
- [Data Pipeline](https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/data_pipeline/src/data_pipeline/pipelines/processor.py): `agents/sub_agents/data_pipeline/src/data_pipeline/pipelines/processor.py`
- [Data Validation](https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/data_validation/src/data_validation/validators/device_session.py): `agents/sub_agents/data_validation/src/data_validation/validators/device_session.py`
- [Cohort Clustering](https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/group_identification/src/group_identification/identifier/louvain.py): `agents/sub_agents/group_identification/src/group_identification/identifier/louvain.py`
- [Knowledge Insights](https://github.com/momakkawi/agentic_tracking_system/blob/main/agents/sub_agents/knowledge_insight/src/knowledge_insight/core/data_insighter.py): `agents/sub_agents/knowledge_insight/src/knowledge_insight/core/data_insighter.py`

### Shared Services

- [File Repositories](https://github.com/momakkawi/agentic_tracking_system/blob/main/utils/src/utils/storage/factory.py): `utils/src/utils/storage/factory.py`
- [Hot-Reload Config](https://github.com/momakkawi/agentic_tracking_system/blob/main/utils/src/utils/config.py): `utils/src/utils/config.py`
- [AI Model Wrappers](https://github.com/momakkawi/agentic_tracking_system/blob/main/utils/src/utils/models/gemini.py): `utils/src/utils/models/gemini.py`

### Other components

- **Administrator**

## Connections

- Administrator → Dashboard: uses (evidence: `README.md`)
- Dashboard → Attendance View: routes to (evidence: `dashboard/src/App.jsx`)
- Dashboard → Alerts View: routes to (evidence: `dashboard/src/App.jsx`)
- Dashboard → Groups View: routes to (evidence: `dashboard/src/App.jsx`)
- Dashboard → Agent Chat: routes to (evidence: `dashboard/src/App.jsx`)
- Dashboard → API Client: uses
- API Client → FastAPI App: HTTP requests (evidence: `README.md`)
- FastAPI App → REST Routes: registers (evidence: `api/main.py`)
- FastAPI App → Orchestrator: dispatches (evidence: `README.md`)
- FastAPI App → Session Service: provides services
- FastAPI App → Alert Service: provides services
- FastAPI App → Chat Service: provides services
- FastAPI App → Event Scheduler: provides services
- Session Service → File Repositories: reads sessions (evidence: `api/services/session_service.py`)
- Alert Service → File Repositories: reads alerts (evidence: `api/services/alert_service.py`)
- Chat Service → File Repositories: persists chats (evidence: `api/services/chat_service.py`)
- Event Scheduler → Orchestrator: triggers workflows (evidence: `README.md`)
- Orchestrator → Conversation Memory: consults (evidence: `README.md`)
- Orchestrator → Data Pipeline: coordinates (evidence: `README.md`)
- Orchestrator → Data Validation: coordinates (evidence: `README.md`)
- Orchestrator → Cohort Clustering: coordinates (evidence: `README.md`)
- Orchestrator → Knowledge Insights: coordinates (evidence: `README.md`)
- Data Pipeline → File Repositories: uses repositories (evidence: `README.md`)
- Orchestrator → Hot-Reload Config: uses (evidence: `README.md`)
- Orchestrator → AI Model Wrappers: uses
