# ahmad-nba/umi architecture

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

- Interactive diagram: https://gitdiagram.com/ahmad-nba/umi
- Repository: https://github.com/ahmad-nba/umi

## Overview

Feedback Watch Tower is a FastAPI-backed feedback and issue-resolution workflow with a Next.js interface. Reporters submit feedback directly or through a conversation; feedback is analyzed and routed into an issue, then handlers advance it through resolution and reporter confirmation. QA users can inspect issue status and history. The excerpts substantiate the workflow, persistence, notifications, and QA services; the README establishes a separately run web frontend. Some API and frontend wiring is therefore shown only at the documented boundary.

Main entry points: [`web/lib/api.ts`](https://github.com/ahmad-nba/umi/blob/main/web/lib/api.ts) (API client), [`app/core/database.py`](https://github.com/ahmad-nba/umi/blob/main/app/core/database.py) (Application database), [`app/services/workflow_service.py`](https://github.com/ahmad-nba/umi/blob/main/app/services/workflow_service.py) (Workflow orchestration), [`app/api/feedback.py`](https://github.com/ahmad-nba/umi/blob/main/app/api/feedback.py) (Feedback endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_web_ui["Reporter and QA pages"]
  node_web_handler["Handler pages"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API entry points"]
  node_feedback_api["Feedback endpoints<br/>[feedback.py]"]
  node_conversation_api["Conversation endpoints<br/>[conversations.py]"]
  node_workflow_api["Workflow endpoints<br/>[workflow.py]"]
  node_issues_api["Issue endpoints<br/>[issues.py]"]
  node_qa_api["QA endpoints<br/>[qa.py]"]
  node_notifications_api["Notification endpoints<br/>[notifications.py]"]
end

subgraph group_workflow["Feedback workflow"]
  node_conversations["Conversation capture"]
  node_feedback["Feedback records"]
  node_workflow_service["Workflow orchestration"]
  node_classifier["Feedback classification<br/>[classifier.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_operations["Issue operations"]
  node_routing["Handler routing<br/>[routing_service.py]"]
  node_issue_service["Issue records<br/>[issue_service.py]"]
  node_qa_service["QA dashboard and history<br/>[qa_service.py]"]
  node_notification_service["Reporter notifications"]
end

subgraph group_data["Persistence"]
  node_database[("Application database<br/>[database.py]")]
end

node_reporter(("Reporter"))
node_handler(("Issue handler"))
node_qa_user(("QA user"))
node_openrouter{{"OpenRouter"}}

node_reporter -->|"uses"| node_web_ui
node_handler -->|"uses"| node_web_handler
node_qa_user -->|"uses"| node_web_ui
node_web_ui -->|"requests"| node_api_client
node_web_handler -->|"requests"| node_api_client
node_api_client -->|"calls"| node_feedback_api
node_api_client -->|"calls"| node_conversation_api
node_api_client -->|"calls"| node_workflow_api
node_api_client -->|"calls"| node_issues_api
node_api_client -->|"calls"| node_qa_api
node_api_client -->|"calls"| node_notifications_api
node_feedback_api -->|"creates and lists"| node_feedback
node_feedback_api -->|"processes and routes"| node_workflow_service
node_conversation_api -->|"manages"| node_conversations
node_conversations -->|"submits as"| node_feedback
node_workflow_api -->|"advances issues"| node_workflow_service
node_issues_api -->|"manages"| node_issue_service
node_qa_api -->|"queries"| node_qa_service
node_notifications_api -->|"lists"| node_notification_service
node_workflow_service -->|"analyzes with"| node_classifier
node_workflow_service -->|"routes with"| node_routing
node_workflow_service -->|"notifies through"| node_notification_service
node_llm -.->|"requests analysis"| node_openrouter
node_conversations -->|"reads and writes"| node_database
node_feedback -->|"reads and writes"| node_database
node_workflow_service -->|"reads and writes"| node_database
node_routing -->|"reads and writes"| node_database
node_issue_service -->|"reads and writes"| node_database
node_qa_service -->|"reads"| node_database
node_notification_service -->|"reads and writes"| node_database

click node_web_ui "https://github.com/ahmad-nba/umi/tree/main/web/app"
click node_web_handler "https://github.com/ahmad-nba/umi/tree/main/web/app/handler"
click node_api_client "https://github.com/ahmad-nba/umi/blob/main/web/lib/api.ts"
click node_feedback_api "https://github.com/ahmad-nba/umi/blob/main/app/api/feedback.py"
click node_conversation_api "https://github.com/ahmad-nba/umi/blob/main/app/api/conversations.py"
click node_workflow_api "https://github.com/ahmad-nba/umi/blob/main/app/api/workflow.py"
click node_issues_api "https://github.com/ahmad-nba/umi/blob/main/app/api/issues.py"
click node_qa_api "https://github.com/ahmad-nba/umi/blob/main/app/api/qa.py"
click node_notifications_api "https://github.com/ahmad-nba/umi/blob/main/app/api/notifications.py"
click node_conversations "https://github.com/ahmad-nba/umi/blob/main/app/services/conversation_service.py"
click node_feedback "https://github.com/ahmad-nba/umi/blob/main/app/services/feedback_service.py"
click node_workflow_service "https://github.com/ahmad-nba/umi/blob/main/app/services/workflow_service.py"
click node_classifier "https://github.com/ahmad-nba/umi/blob/main/app/agents/classifier.py"
click node_llm "https://github.com/ahmad-nba/umi/blob/main/app/agents/llm_client.py"
click node_routing "https://github.com/ahmad-nba/umi/blob/main/app/services/routing_service.py"
click node_issue_service "https://github.com/ahmad-nba/umi/blob/main/app/services/issue_service.py"
click node_qa_service "https://github.com/ahmad-nba/umi/blob/main/app/services/qa_service.py"
click node_notification_service "https://github.com/ahmad-nba/umi/blob/main/app/services/notification_service.py"
click node_database "https://github.com/ahmad-nba/umi/blob/main/app/core/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_web_ui,node_web_handler,node_api_client,node_qa_user toneBlue
class node_feedback_api,node_conversation_api,node_workflow_api,node_issues_api,node_qa_api,node_notifications_api toneAmber
class node_conversations,node_feedback,node_workflow_service,node_classifier,node_llm,node_handler,node_openrouter toneMint
class node_routing,node_issue_service,node_qa_service,node_notification_service toneRose
class node_database,node_reporter toneIndigo
```

## Components

### Web interface

- [Reporter and QA pages](https://github.com/ahmad-nba/umi/tree/main/web/app): `web/app`
- [Handler pages](https://github.com/ahmad-nba/umi/tree/main/web/app/handler): `web/app/handler`
- [API client](https://github.com/ahmad-nba/umi/blob/main/web/lib/api.ts): `web/lib/api.ts`

### API entry points

- [Feedback endpoints](https://github.com/ahmad-nba/umi/blob/main/app/api/feedback.py): `app/api/feedback.py`
- [Conversation endpoints](https://github.com/ahmad-nba/umi/blob/main/app/api/conversations.py): `app/api/conversations.py`
- [Workflow endpoints](https://github.com/ahmad-nba/umi/blob/main/app/api/workflow.py): `app/api/workflow.py`
- [Issue endpoints](https://github.com/ahmad-nba/umi/blob/main/app/api/issues.py): `app/api/issues.py`
- [QA endpoints](https://github.com/ahmad-nba/umi/blob/main/app/api/qa.py): `app/api/qa.py`
- [Notification endpoints](https://github.com/ahmad-nba/umi/blob/main/app/api/notifications.py): `app/api/notifications.py`

### Feedback workflow

- [Conversation capture](https://github.com/ahmad-nba/umi/blob/main/app/services/conversation_service.py): `app/services/conversation_service.py`
- [Feedback records](https://github.com/ahmad-nba/umi/blob/main/app/services/feedback_service.py): `app/services/feedback_service.py`
- [Workflow orchestration](https://github.com/ahmad-nba/umi/blob/main/app/services/workflow_service.py): `app/services/workflow_service.py`
- [Feedback classification](https://github.com/ahmad-nba/umi/blob/main/app/agents/classifier.py): `app/agents/classifier.py`
- [LLM client](https://github.com/ahmad-nba/umi/blob/main/app/agents/llm_client.py): `app/agents/llm_client.py`

### Issue operations

- [Handler routing](https://github.com/ahmad-nba/umi/blob/main/app/services/routing_service.py): `app/services/routing_service.py`
- [Issue records](https://github.com/ahmad-nba/umi/blob/main/app/services/issue_service.py): `app/services/issue_service.py`
- [QA dashboard and history](https://github.com/ahmad-nba/umi/blob/main/app/services/qa_service.py): `app/services/qa_service.py`
- [Reporter notifications](https://github.com/ahmad-nba/umi/blob/main/app/services/notification_service.py): `app/services/notification_service.py`

### Persistence

- [Application database](https://github.com/ahmad-nba/umi/blob/main/app/core/database.py): `app/core/database.py`

### Other components

- **Reporter**
- **Issue handler**
- **QA user**
- **OpenRouter**

## Connections

- Reporter → Reporter and QA pages: uses
- Issue handler → Handler pages: uses
- QA user → Reporter and QA pages: uses
- Reporter and QA pages → API client: requests
- Handler pages → API client: requests
- API client → Feedback endpoints: calls
- API client → Conversation endpoints: calls
- API client → Workflow endpoints: calls
- API client → Issue endpoints: calls
- API client → QA endpoints: calls
- API client → Notification endpoints: calls
- Feedback endpoints → Feedback records: creates and lists
- Feedback endpoints → Workflow orchestration: processes and routes
- Conversation endpoints → Conversation capture: manages
- Conversation capture → Feedback records: submits as
- Workflow endpoints → Workflow orchestration: advances issues
- Issue endpoints → Issue records: manages
- QA endpoints → QA dashboard and history: queries
- Notification endpoints → Reporter notifications: lists
- Workflow orchestration → Feedback classification: analyzes with
- Workflow orchestration → Handler routing: routes with
- Workflow orchestration → Reporter notifications: notifies through
- LLM client → OpenRouter: requests analysis
- Conversation capture → Application database: reads and writes
- Feedback records → Application database: reads and writes
- Workflow orchestration → Application database: reads and writes
- Handler routing → Application database: reads and writes
- Issue records → Application database: reads and writes
- QA dashboard and history → Application database: reads
- Reporter notifications → Application database: reads and writes