# nashiman-01/apna-wakeel-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/nashiman-01/apna-wakeel-hackathon
- Repository: https://github.com/nashiman-01/apna-wakeel-hackathon

## Overview

Apna Wakeel is a multilingual legal-information and navigation product for Pakistan. A person describes a problem through the web app; the backend can request clarification, classify the matter, research official sources, verify claims, and return a practical plan with referrals. The frontend also supports sign-in, conversation history, document handling, and voice input. The README documents these capabilities and the intended Groq, Supabase, and database integrations. Several page and API implementations were not excerpted, so those connections are shown only where documented or indexed.

Main entry points: [`bknd/app/agents/orchestrator.py`](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/orchestrator.py) (Case orchestrator), [`bknd/app/main.py`](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/main.py) (FastAPI app), [`apna-wakeel-frontend/src/App.jsx`](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/App.jsx) (App routing), [`apna-wakeel-frontend/src/pages/Dashboard.jsx`](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/pages/Dashboard.jsx) (Case workspace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["App routing<br/>[App.jsx]"]
  node_dashboard["Case workspace<br/>[Dashboard.jsx]"]
  node_public["Public analysis<br/>[PublicAnalysis.jsx]"]
  node_voice["Voice input<br/>[Voice.jsx]"]
  node_voiceflow["Transcript flow<br/>[voiceFlow.js]"]
  node_speech["Speech services<br/>[speech.js]"]
  node_documents["Document tools<br/>[documents.js]"]
  node_language["Language context"]
  node_api["API client<br/>[api.js]"]
  node_authui["Auth client<br/>[auth.js]"]
end

subgraph group_backend["Backend workflow"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_conversation["Conversation API<br/>[conversations.py]"]
  node_legalapi["Legal API<br/>[legal.py]"]
  node_documentapi["Document API<br/>[documents.py]"]
  node_authapi["Auth API<br/>[auth.py]"]
  node_orchestrator["Case orchestrator<br/>[orchestrator.py]"]
  node_intake["Intake agent<br/>[intake_agent.py]"]
  node_classification["Classification agent"]
  node_followup["Follow-up agent<br/>[followup_agent.py]"]
  node_research["Research agent<br/>[research_agent.py]"]
  node_verification["Claim verification"]
  node_response["Response agent<br/>[response_agent.py]"]
  node_ai["Groq AI service<br/>[ai_service.py]"]
end

subgraph group_sources["Legal information"]
  node_registry["Official source registry<br/>[source_registry.py]"]
  node_evidenceretriever["Evidence retrieval"]
  node_statuteretriever["Statute retrieval"]
  node_evidence["Evidence records<br/>[evidence.py]"]
  node_domain["Legal domains<br/>[domain_catalog.py]"]
  node_referrals["Legal-aid referrals<br/>[referrals.py]"]
end

subgraph group_state["Identity and state"]
  node_db[("Conversation database<br/>[connection.py]")]
end

node_person(("Person"))
node_supabase["Supabase Auth"]
node_official["Official sources"]

node_person -->|"uses"| node_app
node_app -->|"routes to"| node_dashboard
node_app -->|"routes to"| node_public
node_dashboard -->|"requests cases"| node_api
node_dashboard -->|"manages files"| node_documents
node_dashboard -->|"sends transcript"| node_voiceflow
node_voice -->|"uses"| node_speech
node_voice -->|"uses"| node_voiceflow
node_voiceflow -.->|"submits case"| node_api
node_public -->|"submits analysis"| node_api
node_app -->|"uses language"| node_language
node_api -->|"calls backend"| node_fastapi
node_authui -->|"calls auth routes"| node_authapi
node_fastapi -->|"mounts router"| node_conversation
node_fastapi -->|"mounts router"| node_legalapi
node_fastapi -->|"mounts router"| node_documentapi
node_fastapi -->|"mounts router"| node_authapi
node_conversation -->|"runs case"| node_orchestrator
node_conversation -->|"reads and writes"| node_db
node_legalapi -->|"runs analysis"| node_orchestrator
node_legalapi -->|"gets referrals"| node_referrals
node_orchestrator -->|"calls"| node_intake
node_orchestrator -->|"calls"| node_classification
node_orchestrator -->|"calls"| node_followup
node_orchestrator -->|"calls"| node_research
node_orchestrator -->|"calls"| node_verification
node_orchestrator -->|"calls"| node_response
node_orchestrator -->|"uses"| node_registry
node_orchestrator -->|"retrieves evidence"| node_evidenceretriever
node_orchestrator -->|"retrieves statutes"| node_statuteretriever
node_orchestrator -->|"uses domains"| node_domain
node_research -->|"generates research"| node_ai
node_verification -->|"checks claims"| node_ai
node_evidenceretriever -->|"selects sources"| node_registry
node_evidenceretriever -->|"creates records"| node_evidence
node_statuteretriever -->|"selects sources"| node_registry
node_statuteretriever -->|"creates records"| node_evidence
node_statuteretriever -->|"fetches statutes"| node_official
node_authapi -->|"validates identity"| node_supabase
node_authui -->|"requests reset"| node_supabase
node_documentapi -.->|"stores metadata"| node_db

click node_app "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/App.jsx"
click node_dashboard "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/pages/Dashboard.jsx"
click node_public "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/pages/PublicAnalysis.jsx"
click node_voice "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/pages/Voice.jsx"
click node_voiceflow "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/voiceFlow.js"
click node_speech "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/speech.js"
click node_documents "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/documents.js"
click node_language "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/i18n/LanguageContext.jsx"
click node_api "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/api.js"
click node_authui "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/auth.js"
click node_fastapi "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/main.py"
click node_conversation "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/conversations.py"
click node_legalapi "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/legal.py"
click node_documentapi "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/documents.py"
click node_authapi "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/auth.py"
click node_orchestrator "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/orchestrator.py"
click node_intake "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/intake_agent.py"
click node_classification "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/classification_agent.py"
click node_followup "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/followup_agent.py"
click node_research "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/research_agent.py"
click node_verification "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/verification_agent.py"
click node_response "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/response_agent.py"
click node_registry "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/source_registry.py"
click node_evidenceretriever "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/evidence_retriever.py"
click node_statuteretriever "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/statute_retriever.py"
click node_evidence "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/evidence.py"
click node_domain "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/domain_catalog.py"
click node_referrals "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/referrals.py"
click node_ai "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/services/ai_service.py"
click node_db "https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/database/connection.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_dashboard,node_public,node_voice,node_voiceflow,node_speech,node_documents,node_language,node_api,node_authui toneBlue
class node_fastapi,node_conversation,node_legalapi,node_documentapi,node_authapi,node_orchestrator,node_intake,node_classification,node_followup,node_research,node_verification,node_response,node_ai toneAmber
class node_registry,node_evidenceretriever,node_statuteretriever,node_evidence,node_domain,node_referrals toneMint
class node_db toneRose
class node_person,node_supabase,node_official toneIndigo
```

## Components

### Web experience

- [App routing](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/App.jsx): `apna-wakeel-frontend/src/App.jsx`
- [Case workspace](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/pages/Dashboard.jsx): `apna-wakeel-frontend/src/pages/Dashboard.jsx`
- [Public analysis](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/pages/PublicAnalysis.jsx): `apna-wakeel-frontend/src/pages/PublicAnalysis.jsx`
- [Voice input](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/pages/Voice.jsx): `apna-wakeel-frontend/src/pages/Voice.jsx`
- [Transcript flow](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/voiceFlow.js): `apna-wakeel-frontend/src/services/voiceFlow.js`
- [Speech services](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/speech.js): `apna-wakeel-frontend/src/services/speech.js`
- [Document tools](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/documents.js): `apna-wakeel-frontend/src/services/documents.js`
- [Language context](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/i18n/LanguageContext.jsx): `apna-wakeel-frontend/src/i18n/LanguageContext.jsx`
- [API client](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/api.js): `apna-wakeel-frontend/src/services/api.js`
- [Auth client](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/apna-wakeel-frontend/src/services/auth.js): `apna-wakeel-frontend/src/services/auth.js`

### Backend workflow

- [FastAPI app](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/main.py): `bknd/app/main.py`
- [Conversation API](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/conversations.py): `bknd/app/api/conversations.py`
- [Legal API](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/legal.py): `bknd/app/api/legal.py`
- [Document API](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/documents.py): `bknd/app/api/documents.py`
- [Auth API](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/api/auth.py): `bknd/app/api/auth.py`
- [Case orchestrator](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/orchestrator.py): `bknd/app/agents/orchestrator.py`
- [Intake agent](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/intake_agent.py): `bknd/app/agents/intake_agent.py`
- [Classification agent](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/classification_agent.py): `bknd/app/agents/classification_agent.py`
- [Follow-up agent](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/followup_agent.py): `bknd/app/agents/followup_agent.py`
- [Research agent](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/research_agent.py): `bknd/app/agents/research_agent.py`
- [Claim verification](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/verification_agent.py): `bknd/app/agents/verification_agent.py`
- [Response agent](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/agents/response_agent.py): `bknd/app/agents/response_agent.py`
- [Groq AI service](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/services/ai_service.py): `bknd/app/services/ai_service.py`

### Legal information

- [Official source registry](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/source_registry.py): `bknd/app/legal_sources/source_registry.py`
- [Evidence retrieval](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/evidence_retriever.py): `bknd/app/legal_sources/evidence_retriever.py`
- [Statute retrieval](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/statute_retriever.py): `bknd/app/legal_sources/statute_retriever.py`
- [Evidence records](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/evidence.py): `bknd/app/legal_sources/evidence.py`
- [Legal domains](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/domain_catalog.py): `bknd/app/legal_sources/domain_catalog.py`
- [Legal-aid referrals](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/legal_sources/referrals.py): `bknd/app/legal_sources/referrals.py`

### Identity and state

- [Conversation database](https://github.com/nashiman-01/apna-wakeel-hackathon/blob/main/bknd/app/database/connection.py): `bknd/app/database/connection.py`

### Other components

- **Person**
- **Supabase Auth**
- **Official sources**

## Connections

- Person → App routing: uses
- App routing → Case workspace: routes to (evidence: `apna-wakeel-frontend/src/App.jsx`)
- App routing → Public analysis: routes to (evidence: `apna-wakeel-frontend/src/App.jsx`)
- Case workspace → API client: requests cases (evidence: `apna-wakeel-frontend/src/pages/Dashboard.jsx`)
- Case workspace → Document tools: manages files (evidence: `apna-wakeel-frontend/src/pages/Dashboard.jsx`)
- Case workspace → Transcript flow: sends transcript (evidence: `apna-wakeel-frontend/src/pages/Dashboard.jsx`)
- Voice input → Speech services: uses (evidence: `apna-wakeel-frontend/src/pages/Voice.jsx`)
- Voice input → Transcript flow: uses (evidence: `apna-wakeel-frontend/src/pages/Voice.jsx`)
- Transcript flow → API client: submits case
- Public analysis → API client: submits analysis (evidence: `apna-wakeel-frontend/src/pages/PublicAnalysis.jsx`)
- App routing → Language context: uses language (evidence: `apna-wakeel-frontend/src/App.jsx`)
- API client → FastAPI app: calls backend
- Auth client → Auth API: calls auth routes
- FastAPI app → Conversation API: mounts router (evidence: `bknd/app/main.py`)
- FastAPI app → Legal API: mounts router (evidence: `bknd/app/main.py`)
- FastAPI app → Document API: mounts router (evidence: `bknd/app/main.py`)
- FastAPI app → Auth API: mounts router (evidence: `bknd/app/main.py`)
- Conversation API → Case orchestrator: runs case (evidence: `bknd/app/api/conversations.py`)
- Conversation API → Conversation database: reads and writes (evidence: `bknd/app/api/conversations.py`)
- Legal API → Case orchestrator: runs analysis (evidence: `bknd/app/api/legal.py`)
- Legal API → Legal-aid referrals: gets referrals (evidence: `bknd/app/api/legal.py`)
- Case orchestrator → Intake agent: calls (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Classification agent: calls (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Follow-up agent: calls (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Research agent: calls (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Claim verification: calls (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Response agent: calls (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Official source registry: uses (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Evidence retrieval: retrieves evidence (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Statute retrieval: retrieves statutes (evidence: `bknd/app/agents/orchestrator.py`)
- Case orchestrator → Legal domains: uses domains (evidence: `bknd/app/agents/orchestrator.py`)
- Research agent → Groq AI service: generates research (evidence: `bknd/app/agents/research_agent.py`)
- Claim verification → Groq AI service: checks claims (evidence: `bknd/app/agents/verification_agent.py`)
- Evidence retrieval → Official source registry: selects sources (evidence: `bknd/app/legal_sources/evidence_retriever.py`)
- Evidence retrieval → Evidence records: creates records (evidence: `bknd/app/legal_sources/evidence_retriever.py`)
- Statute retrieval → Official source registry: selects sources (evidence: `bknd/app/legal_sources/statute_retriever.py`)
- Statute retrieval → Evidence records: creates records (evidence: `bknd/app/legal_sources/statute_retriever.py`)
- Statute retrieval → Official sources: fetches statutes (evidence: `bknd/app/legal_sources/statute_retriever.py`)
- Auth API → Supabase Auth: validates identity (evidence: `bknd/app/api/auth.py`)
- Auth client → Supabase Auth: requests reset (evidence: `apna-wakeel-frontend/src/services/auth.js`)
- Document API → Conversation database: stores metadata
