# bourzat/sikika-ai architecture

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

- Interactive diagram: https://gitdiagram.com/bourzat/sikika-ai
- Repository: https://github.com/bourzat/sikika-ai

## Overview

Sikika AI is a Nairobi road-grievance reporting and risk-intelligence application. Citizens submit complaints in the Streamlit portal; the app classifies issue and priority, stores tickets, and supports tracking, analytics, and administrative status updates. Its API exposes grievance and regional-risk data, while a developer portal offers M-Pesa payment for API access. The excerpts show dashboard calls into classification and storage, and API reads from storage; omitted dashboard sections limit certainty about notification and payment call sites.

Main entry points: [`dashboard.py`](https://github.com/bourzat/sikika-ai/blob/main/dashboard.py) (Reporting Portal), [`database.py`](https://github.com/bourzat/sikika-ai/blob/main/database.py) (Ticket Database), [`notifications.py`](https://github.com/bourzat/sikika-ai/blob/main/notifications.py) (Email Notifications), [`ml_engine.py`](https://github.com/bourzat/sikika-ai/blob/main/ml_engine.py) (Complaint Classifier)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_citizen_ops["Grievance Operations"]
  node_dashboard["Reporting Portal<br/>[dashboard.py]"]
  node_tracking["Ticket Tracking<br/>[dashboard.py]"]
  node_admin["Admin Resolution<br/>[dashboard.py]"]
end

subgraph group_intelligence["Risk Intelligence"]
  node_analytics["Operational Analytics<br/>[dashboard.py]"]
  node_classifier["Complaint Classifier<br/>[ml_engine.py]"]
  node_cluster_analysis["Hotspot Clustering<br/>[ml_engine.py]"]
end

subgraph group_data_access["Data Access"]
  node_api_gateway["Data API<br/>[api.py]"]
  node_risk_api["Risk Intelligence API<br/>[api.py]"]
  node_ticket_store[("Ticket Database<br/>[database.py]")]
end

subgraph group_integrations["External Integrations"]
  node_email_notifications["Email Notifications<br/>[notifications.py]"]
  node_mpesa_payment["M-Pesa Payments<br/>[mpesa.py]"]
end

node_citizen(("Citizen"))
node_safaricom{{"Safaricom Daraja"}}
node_smtp{{"Gmail SMTP"}}
node_developer(("API Customer"))

node_citizen -->|"submits complaint"| node_dashboard
node_dashboard -->|"classifies complaint"| node_classifier
node_dashboard -->|"saves ticket"| node_ticket_store
node_dashboard -->|"opens tracking"| node_tracking
node_tracking -->|"loads tickets"| node_ticket_store
node_dashboard -->|"opens analytics"| node_analytics
node_dashboard -->|"opens administration"| node_admin
node_admin -->|"updates status"| node_ticket_store
node_api_gateway -->|"loads tickets"| node_ticket_store
node_risk_api -->|"loads tickets"| node_ticket_store
node_classifier -->|"clusters tickets"| node_cluster_analysis
node_developer -->|"requests API access"| node_dashboard
node_dashboard -->|"triggers payment"| node_mpesa_payment
node_mpesa_payment -->|"requests STK push"| node_safaricom
node_email_notifications -->|"sends email"| node_smtp
node_admin -.->|"notifies citizen"| node_email_notifications
node_dashboard -.->|"confirms submission"| node_email_notifications

click node_dashboard "https://github.com/bourzat/sikika-ai/blob/main/dashboard.py"
click node_tracking "https://github.com/bourzat/sikika-ai/blob/main/dashboard.py"
click node_admin "https://github.com/bourzat/sikika-ai/blob/main/dashboard.py"
click node_analytics "https://github.com/bourzat/sikika-ai/blob/main/dashboard.py"
click node_classifier "https://github.com/bourzat/sikika-ai/blob/main/ml_engine.py"
click node_cluster_analysis "https://github.com/bourzat/sikika-ai/blob/main/ml_engine.py"
click node_api_gateway "https://github.com/bourzat/sikika-ai/blob/main/api.py"
click node_risk_api "https://github.com/bourzat/sikika-ai/blob/main/api.py"
click node_ticket_store "https://github.com/bourzat/sikika-ai/blob/main/database.py"
click node_email_notifications "https://github.com/bourzat/sikika-ai/blob/main/notifications.py"
click node_mpesa_payment "https://github.com/bourzat/sikika-ai/blob/main/mpesa.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_tracking,node_admin toneBlue
class node_analytics,node_classifier,node_cluster_analysis toneAmber
class node_api_gateway,node_risk_api,node_ticket_store,node_developer toneMint
class node_email_notifications,node_mpesa_payment toneRose
class node_citizen,node_safaricom,node_smtp toneIndigo
```

## Components

### Grievance Operations

- [Reporting Portal](https://github.com/bourzat/sikika-ai/blob/main/dashboard.py): `dashboard.py`
- [Ticket Tracking](https://github.com/bourzat/sikika-ai/blob/main/dashboard.py): `dashboard.py`
- [Admin Resolution](https://github.com/bourzat/sikika-ai/blob/main/dashboard.py): `dashboard.py`

### Risk Intelligence

- [Operational Analytics](https://github.com/bourzat/sikika-ai/blob/main/dashboard.py): `dashboard.py`
- [Complaint Classifier](https://github.com/bourzat/sikika-ai/blob/main/ml_engine.py): `ml_engine.py`
- [Hotspot Clustering](https://github.com/bourzat/sikika-ai/blob/main/ml_engine.py): `ml_engine.py`

### Data Access

- [Data API](https://github.com/bourzat/sikika-ai/blob/main/api.py): `api.py`
- [Risk Intelligence API](https://github.com/bourzat/sikika-ai/blob/main/api.py): `api.py`
- [Ticket Database](https://github.com/bourzat/sikika-ai/blob/main/database.py): `database.py`

### External Integrations

- [Email Notifications](https://github.com/bourzat/sikika-ai/blob/main/notifications.py): `notifications.py`
- [M-Pesa Payments](https://github.com/bourzat/sikika-ai/blob/main/mpesa.py): `mpesa.py`

### Other components

- **Citizen**
- **Safaricom Daraja**
- **Gmail SMTP**
- **API Customer**

## Connections

- Citizen → Reporting Portal: submits complaint (evidence: `dashboard.py`)
- Reporting Portal → Complaint Classifier: classifies complaint (evidence: `dashboard.py`)
- Reporting Portal → Ticket Database: saves ticket (evidence: `dashboard.py`)
- Reporting Portal → Ticket Tracking: opens tracking (evidence: `dashboard.py`)
- Ticket Tracking → Ticket Database: loads tickets (evidence: `dashboard.py`)
- Reporting Portal → Operational Analytics: opens analytics (evidence: `dashboard.py`)
- Reporting Portal → Admin Resolution: opens administration (evidence: `dashboard.py`)
- Admin Resolution → Ticket Database: updates status (evidence: `dashboard.py`)
- Data API → Ticket Database: loads tickets (evidence: `api.py`)
- Risk Intelligence API → Ticket Database: loads tickets (evidence: `api.py`)
- Complaint Classifier → Hotspot Clustering: clusters tickets (evidence: `ml_engine.py`)
- API Customer → Reporting Portal: requests API access (evidence: `dashboard.py`)
- Reporting Portal → M-Pesa Payments: triggers payment (evidence: `dashboard.py`)
- M-Pesa Payments → Safaricom Daraja: requests STK push (evidence: `mpesa.py`)
- Email Notifications → Gmail SMTP: sends email (evidence: `notifications.py`)
- Admin Resolution → Email Notifications: notifies citizen (evidence: `dashboard.py`)
- Reporting Portal → Email Notifications: confirms submission (evidence: `dashboard.py`)