# husnaqayyum99-byte/hks architecture

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

- Interactive diagram: https://gitdiagram.com/husnaqayyum99-byte/hks
- Repository: https://github.com/husnaqayyum99-byte/hks

## Overview

Apna Wakeel is a Pakistan-focused legal information and navigation product: users describe a legal problem, answer follow-up questions, and receive an evidence-backed response; signed-in users can also manage chat history, documents, and voice input. The frontend provides the user workflow and account experience, while the FastAPI backend exposes authentication, conversation, legal, and document routes. The sampled orchestrator shows a staged case-analysis pipeline. Some frontend-to-backend wiring and unsampled route internals are not shown, so those relationships are omitted rather than inferred.

Main entry points: [`bknd/app/agents/orchestrator.py`](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/orchestrator.py) (Case orchestrator), [`apna-wakeel-frontend/src/App.jsx`](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/App.jsx) (App workflow), [`bknd/app/main.py`](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/main.py) (FastAPI application), [`bknd/app/services/ai_service.py`](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/services/ai_service.py) (AI model service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend experience"]
  node_app["App workflow<br/>[App.jsx]"]
  node_describe["Problem intake<br/>[Describe.jsx]"]
  node_followup_ui["Clarification<br/>[FollowUp.jsx]"]
  node_analysis_ui["Analysis view<br/>[Analysis.jsx]"]
  node_results_ui["Legal results<br/>[Results.jsx]"]
  node_dashboard["Chat workspace<br/>[Dashboard.jsx]"]
  node_voice_ui["Voice experience<br/>[Voice.jsx]"]
  node_speech["Speech service<br/>[speech.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_auth_ui["Auth client<br/>[auth.js]"]
  node_auth_context["Auth state<br/>[AuthContext.jsx]"]
  node_language["Language support"]
end

subgraph group_backend_api["Backend API"]
  node_api_entry["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_conversation_routes["Conversation routes<br/>[conversations.py]"]
  node_legal_routes["Legal routes<br/>[legal.py]"]
  node_document_routes["Document routes<br/>[documents.py]"]
end

subgraph group_case_pipeline["Case analysis"]
  node_orchestrator["Case orchestrator<br/>[orchestrator.py]"]
  node_intake_agent["Case intake<br/>[intake_agent.py]"]
  node_classification_agent["Case classification"]
  node_followup_agent["Follow-up generation<br/>[followup_agent.py]"]
  node_research_agent["Research planning<br/>[research_agent.py]"]
  node_verification_agent["Claim verification"]
  node_response_agent["Response generation<br/>[response_agent.py]"]
end

subgraph group_legal_sources["Legal sources"]
  node_source_registry["Source registry<br/>[source_registry.py]"]
  node_evidence_retriever["Evidence retrieval"]
  node_statute_retriever["Statute retrieval"]
  node_evidence["Evidence record<br/>[evidence.py]"]
end

subgraph group_platform["Platform services"]
  node_ai_service["AI model service<br/>[ai_service.py]"]
  node_database[("Conversation database<br/>[connection.py]")]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_supabase["Supabase<br/>[supabase_client.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

node_user(("Legal help seeker"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_describe
node_app -->|"renders"| node_followup_ui
node_app -->|"renders"| node_analysis_ui
node_app -->|"renders"| node_results_ui
node_app -->|"renders"| node_dashboard
node_app -->|"reads auth state"| node_auth_context
node_describe -->|"continues to"| node_followup_ui
node_followup_ui -->|"continues to"| node_analysis_ui
node_analysis_ui -->|"continues to"| node_results_ui
node_dashboard -->|"calls"| node_api_client
node_voice_ui -->|"uses"| node_speech
node_auth_context -->|"uses"| node_auth_ui
node_auth_ui -.->|"requests auth API"| node_api_entry
node_api_entry -->|"registers"| node_auth_routes
node_api_entry -->|"registers"| node_conversation_routes
node_api_entry -->|"registers"| node_legal_routes
node_api_entry -->|"registers"| node_document_routes
node_conversation_routes -->|"processes cases"| node_orchestrator
node_conversation_routes -->|"reads and writes"| node_database
node_document_routes -->|"uses"| node_database
node_auth_routes -->|"delegates"| node_auth_service
node_auth_service -->|"authenticates with"| node_supabase
node_orchestrator -->|"calls"| node_intake_agent
node_orchestrator -->|"classifies with"| node_classification_agent
node_orchestrator -->|"requests questions"| node_followup_agent
node_orchestrator -->|"plans research"| node_research_agent
node_orchestrator -->|"verifies claims"| node_verification_agent
node_orchestrator -->|"generates response"| node_response_agent
node_orchestrator -->|"selects sources"| node_source_registry
node_orchestrator -->|"collects evidence"| node_evidence_retriever
node_orchestrator -->|"collects statutes"| node_statute_retriever
node_evidence_retriever -->|"uses registry"| node_source_registry
node_evidence_retriever -->|"builds records"| node_evidence
node_statute_retriever -->|"uses records"| node_evidence
node_research_agent -->|"generates plan"| node_ai_service
node_response_agent -->|"generates response"| node_ai_service
node_verification_agent -->|"checks claims"| node_ai_service
node_response_agent -->|"uses evidence"| node_evidence
node_verification_agent -->|"uses evidence"| node_evidence
node_ai_service -->|"reads model config"| node_settings
node_database -->|"reads DB config"| node_settings
node_api_entry -->|"initializes schema"| node_database
node_supabase -.->|"reads credentials"| node_settings

click node_app "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/App.jsx"
click node_describe "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Describe.jsx"
click node_followup_ui "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/FollowUp.jsx"
click node_analysis_ui "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Analysis.jsx"
click node_results_ui "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Results.jsx"
click node_dashboard "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Dashboard.jsx"
click node_voice_ui "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Voice.jsx"
click node_speech "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/services/speech.js"
click node_api_client "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/services/api.js"
click node_auth_ui "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/services/auth.js"
click node_auth_context "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/context/AuthContext.jsx"
click node_language "https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/i18n/LanguageContext.jsx"
click node_api_entry "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/main.py"
click node_auth_routes "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/auth.py"
click node_conversation_routes "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/conversations.py"
click node_legal_routes "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/legal.py"
click node_document_routes "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/documents.py"
click node_orchestrator "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/orchestrator.py"
click node_intake_agent "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/intake_agent.py"
click node_classification_agent "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/classification_agent.py"
click node_followup_agent "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/followup_agent.py"
click node_research_agent "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/research_agent.py"
click node_verification_agent "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/verification_agent.py"
click node_response_agent "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/response_agent.py"
click node_source_registry "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/source_registry.py"
click node_evidence_retriever "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/evidence_retriever.py"
click node_statute_retriever "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/statute_retriever.py"
click node_evidence "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/evidence.py"
click node_ai_service "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/services/ai_service.py"
click node_database "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/database/connection.py"
click node_auth_service "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/services/auth_service.py"
click node_supabase "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/supabase_client.py"
click node_settings "https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/core/config.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_app,node_describe,node_followup_ui,node_analysis_ui,node_results_ui,node_dashboard,node_voice_ui,node_speech,node_api_client,node_auth_ui,node_auth_context,node_language toneBlue
class node_api_entry,node_auth_routes,node_conversation_routes,node_legal_routes,node_document_routes toneAmber
class node_orchestrator,node_intake_agent,node_classification_agent,node_followup_agent,node_research_agent,node_verification_agent,node_response_agent toneMint
class node_source_registry,node_evidence_retriever,node_statute_retriever,node_evidence toneRose
class node_ai_service,node_database,node_auth_service,node_supabase,node_settings,node_user toneIndigo
```

## Components

### Frontend experience

- [App workflow](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/App.jsx): `apna-wakeel-frontend/src/App.jsx`
- [Problem intake](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Describe.jsx): `apna-wakeel-frontend/src/pages/Describe.jsx`
- [Clarification](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/FollowUp.jsx): `apna-wakeel-frontend/src/pages/FollowUp.jsx`
- [Analysis view](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Analysis.jsx): `apna-wakeel-frontend/src/pages/Analysis.jsx`
- [Legal results](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Results.jsx): `apna-wakeel-frontend/src/pages/Results.jsx`
- [Chat workspace](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Dashboard.jsx): `apna-wakeel-frontend/src/pages/Dashboard.jsx`
- [Voice experience](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/pages/Voice.jsx): `apna-wakeel-frontend/src/pages/Voice.jsx`
- [Speech service](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/services/speech.js): `apna-wakeel-frontend/src/services/speech.js`
- [API client](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/services/api.js): `apna-wakeel-frontend/src/services/api.js`
- [Auth client](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/services/auth.js): `apna-wakeel-frontend/src/services/auth.js`
- [Auth state](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/context/AuthContext.jsx): `apna-wakeel-frontend/src/context/AuthContext.jsx`
- [Language support](https://github.com/husnaqayyum99-byte/hks/blob/main/apna-wakeel-frontend/src/i18n/LanguageContext.jsx): `apna-wakeel-frontend/src/i18n/LanguageContext.jsx`

### Backend API

- [FastAPI application](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/main.py): `bknd/app/main.py`
- [Authentication routes](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/auth.py): `bknd/app/api/auth.py`
- [Conversation routes](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/conversations.py): `bknd/app/api/conversations.py`
- [Legal routes](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/legal.py): `bknd/app/api/legal.py`
- [Document routes](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/api/documents.py): `bknd/app/api/documents.py`

### Case analysis

- [Case orchestrator](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/orchestrator.py): `bknd/app/agents/orchestrator.py`
- [Case intake](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/intake_agent.py): `bknd/app/agents/intake_agent.py`
- [Case classification](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/classification_agent.py): `bknd/app/agents/classification_agent.py`
- [Follow-up generation](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/followup_agent.py): `bknd/app/agents/followup_agent.py`
- [Research planning](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/research_agent.py): `bknd/app/agents/research_agent.py`
- [Claim verification](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/verification_agent.py): `bknd/app/agents/verification_agent.py`
- [Response generation](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/agents/response_agent.py): `bknd/app/agents/response_agent.py`

### Legal sources

- [Source registry](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/source_registry.py): `bknd/app/legal_sources/source_registry.py`
- [Evidence retrieval](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/evidence_retriever.py): `bknd/app/legal_sources/evidence_retriever.py`
- [Statute retrieval](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/statute_retriever.py): `bknd/app/legal_sources/statute_retriever.py`
- [Evidence record](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/legal_sources/evidence.py): `bknd/app/legal_sources/evidence.py`

### Platform services

- [AI model service](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/services/ai_service.py): `bknd/app/services/ai_service.py`
- [Conversation database](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/database/connection.py): `bknd/app/database/connection.py`
- [Auth service](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/services/auth_service.py): `bknd/app/services/auth_service.py`
- [Supabase](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/supabase_client.py): `bknd/app/supabase_client.py`
- [Runtime settings](https://github.com/husnaqayyum99-byte/hks/blob/main/bknd/app/core/config.py): `bknd/app/core/config.py`

### Other components

- **Legal help seeker**

## Connections

- Legal help seeker → App workflow: uses (evidence: `apna-wakeel-frontend/src/App.jsx`)
- App workflow → Problem intake: renders (evidence: `apna-wakeel-frontend/src/App.jsx`)
- App workflow → Clarification: renders (evidence: `apna-wakeel-frontend/src/App.jsx`)
- App workflow → Analysis view: renders (evidence: `apna-wakeel-frontend/src/App.jsx`)
- App workflow → Legal results: renders (evidence: `apna-wakeel-frontend/src/App.jsx`)
- App workflow → Chat workspace: renders (evidence: `apna-wakeel-frontend/src/App.jsx`)
- App workflow → Auth state: reads auth state (evidence: `apna-wakeel-frontend/src/App.jsx`)
- Problem intake → Clarification: continues to (evidence: `apna-wakeel-frontend/src/App.jsx`)
- Clarification → Analysis view: continues to (evidence: `apna-wakeel-frontend/src/App.jsx`)
- Analysis view → Legal results: continues to (evidence: `apna-wakeel-frontend/src/App.jsx`)
- Chat workspace → API client: calls (evidence: `apna-wakeel-frontend/src/pages/Dashboard.jsx`)
- Voice experience → Speech service: uses (evidence: `apna-wakeel-frontend/src/pages/Voice.jsx`)
- Auth state → Auth client: uses (evidence: `apna-wakeel-frontend/src/context/AuthContext.jsx`)
- Auth client → FastAPI application: requests auth API
- FastAPI application → Authentication routes: registers (evidence: `bknd/app/main.py`)
- FastAPI application → Conversation routes: registers (evidence: `bknd/app/main.py`)
- FastAPI application → Legal routes: registers (evidence: `bknd/app/main.py`)
- FastAPI application → Document routes: registers (evidence: `bknd/app/main.py`)
- Conversation routes → Case orchestrator: processes cases (evidence: `bknd/app/api/conversations.py`)
- Conversation routes → Conversation database: reads and writes (evidence: `bknd/app/api/conversations.py`)
- Document routes → Conversation database: uses (evidence: `bknd/app/api/documents.py`)
- Authentication routes → Auth service: delegates (evidence: `bknd/app/api/auth.py`)
- Auth service → Supabase: authenticates with (evidence: `bknd/app/services/auth_service.py`)
- Case orchestrator → Case intake: calls (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Case classification: classifies with (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Follow-up generation: requests questions (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Research planning: plans research (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Claim verification: verifies claims (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Response generation: generates response (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Source registry: selects sources (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Evidence retrieval: collects evidence (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Statute retrieval: collects statutes (evidence: `bknd/app/agents/orchestrator.py`)
- Evidence retrieval → Source registry: uses registry (evidence: `bknd/app/legal_sources/evidence_retriever.py`)
- Evidence retrieval → Evidence record: builds records (evidence: `bknd/app/legal_sources/evidence_retriever.py`)
- Statute retrieval → Evidence record: uses records (evidence: `bknd/app/legal_sources/statute_retriever.py`)
- Research planning → AI model service: generates plan (evidence: `bknd/app/agents/research_agent.py`)
- Response generation → AI model service: generates response (evidence: `bknd/app/agents/response_agent.py`)
- Claim verification → AI model service: checks claims (evidence: `bknd/app/agents/verification_agent.py`)
- Response generation → Evidence record: uses evidence (evidence: `bknd/app/agents/response_agent.py`)
- Claim verification → Evidence record: uses evidence (evidence: `bknd/app/agents/verification_agent.py`)
- AI model service → Runtime settings: reads model config (evidence: `bknd/app/services/ai_service.py`)
- Conversation database → Runtime settings: reads DB config (evidence: `bknd/app/database/connection.py`)
- FastAPI application → Conversation database: initializes schema (evidence: `bknd/app/main.py`)
- Supabase → Runtime settings: reads credentials (evidence: `bknd/app/supabase_client.py`)
