# kamalchahal7/arrive architecture

> Architecture diagram of the GitHub repository kamalchahal7/arrive, 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/kamalchahal7/arrive
- Repository: https://github.com/kamalchahal7/arrive

## Overview

Arrive helps newly arrived immigrants get official information in their language, understand next steps, and reach settlement workers; staff also use anonymized needs data. The main flow runs from newcomer pages through the FastAPI API to answers grounded in ingested official sources, or to household checklist and program guidance. Voice, onboarding, letters, scam checks, staff handoffs, and analytics are additional product branches. The README and sampled backend show the principal integrations; several frontend and backend subsystems are represented from documented capabilities and the source index, without asserting their internal calls.

Main entry points: [`backend/app/main.py`](https://github.com/kamalchahal7/arrive/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/ask.py`](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/ask.py) (Answer service), [`ingestion/ingest.py`](https://github.com/kamalchahal7/arrive/blob/main/ingestion/ingest.py) (Source ingestion), [`frontend/src/app/[locale]`](https://github.com/kamalchahal7/arrive/tree/main/frontend/src/app/%5Blocale%5D) (Localized web app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Newcomer experience"]
  node_web["Localized web app"]
  node_checklist_ui["Checklist and programs<br/>[page.tsx]"]
  node_voice_ui["Voice experience<br/>[VoiceAssistant.tsx]"]
end

subgraph group_api["API and domain"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_ask_router["Ask endpoint<br/>[ask.py]"]
  node_ask_service["Answer service<br/>[ask.py]"]
  node_checklist_router["Checklist endpoints<br/>[checklist.py]"]
  node_checklist_service["Household checklist<br/>[checklist.py]"]
  node_voice_router["Voice tools<br/>[voice.py]"]
end

subgraph group_knowledge["Official knowledge"]
  node_ingest_runner["Ingestion scheduler"]
  node_ingest["Source ingestion<br/>[ingest.py]"]
  node_retrieval["Source retrieval<br/>[retrieval.py]"]
  node_embeddings["Embedding helpers<br/>[embeddings.py]"]
end

subgraph group_staff["Staff workflows"]
  node_staff_web["Staff portal<br/>[page.tsx]"]
  node_insights_web["Insights dashboard<br/>[page.tsx]"]
  node_handoff["Worker handoffs<br/>[handoff.py]"]
  node_insights["Needs analytics<br/>[insights.py]"]
end

subgraph group_integrations["External services"]
  node_database[("Tiger Data")]
  node_gemini{{"Gemini"}}
  node_elevenlabs{{"ElevenLabs"}}
  node_auth0{{"Auth0"}}
end

node_newcomer(("Newcomer"))
node_staff_user(("Settlement staff"))
node_official_sources["Official web pages"]

node_newcomer -->|"uses"| node_web
node_web -->|"calls API"| node_api_app
node_api_app -->|"routes"| node_ask_router
node_ask_router -->|"calls"| node_ask_service
node_ask_service -.->|"retrieves sources"| node_retrieval
node_retrieval -->|"embeds query"| node_embeddings
node_embeddings -->|"requests vectors"| node_gemini
node_retrieval -->|"searches passages"| node_database
node_ask_service -->|"generates answers"| node_gemini
node_web -->|"opens"| node_checklist_ui
node_checklist_ui -.->|"calls API"| node_api_app
node_api_app -->|"routes"| node_checklist_router
node_checklist_router -->|"builds checklist"| node_checklist_service
node_checklist_router -.->|"reads progress"| node_database
node_api_app -->|"schedules ingestion"| node_ingest_runner
node_ingest_runner -->|"runs"| node_ingest
node_official_sources -->|"provides pages"| node_ingest
node_ingest -->|"embeds chunks"| node_embeddings
node_ingest -->|"writes chunks"| node_database
node_voice_ui -->|"connects agent"| node_elevenlabs
node_elevenlabs -->|"calls tools"| node_voice_router
node_api_app -->|"routes"| node_voice_router
node_voice_router -->|"calls"| node_ask_service
node_staff_user -->|"uses"| node_staff_web
node_staff_user -->|"uses"| node_insights_web
node_staff_web -->|"authenticates"| node_auth0
node_staff_web -->|"calls API"| node_api_app
node_insights_web -->|"calls API"| node_api_app
node_api_app -.->|"routes handoffs"| node_handoff
node_api_app -.->|"routes analytics"| node_insights
node_insights -->|"aggregates activity"| node_database

click node_web "https://github.com/kamalchahal7/arrive/tree/main/frontend/src/app/%5Blocale%5D"
click node_checklist_ui "https://github.com/kamalchahal7/arrive/blob/main/frontend/src/app/%5Blocale%5D/(app)/roadmap/page.tsx"
click node_voice_ui "https://github.com/kamalchahal7/arrive/blob/main/frontend/src/components/VoiceAssistant.tsx"
click node_staff_web "https://github.com/kamalchahal7/arrive/blob/main/frontend/src/app/(staff)/worker/page.tsx"
click node_insights_web "https://github.com/kamalchahal7/arrive/blob/main/frontend/src/app/(staff)/insights/page.tsx"
click node_api_app "https://github.com/kamalchahal7/arrive/blob/main/backend/app/main.py"
click node_ask_router "https://github.com/kamalchahal7/arrive/blob/main/backend/app/routers/ask.py"
click node_ask_service "https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/ask.py"
click node_checklist_router "https://github.com/kamalchahal7/arrive/blob/main/backend/app/routers/checklist.py"
click node_checklist_service "https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/checklist.py"
click node_voice_router "https://github.com/kamalchahal7/arrive/blob/main/backend/app/routers/voice.py"
click node_ingest_runner "https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/ingestion_runner.py"
click node_ingest "https://github.com/kamalchahal7/arrive/blob/main/ingestion/ingest.py"
click node_retrieval "https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/retrieval.py"
click node_embeddings "https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/embeddings.py"
click node_handoff "https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/handoff.py"
click node_insights "https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/insights.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,node_checklist_ui,node_voice_ui toneBlue
class node_api_app,node_ask_router,node_ask_service,node_checklist_router,node_checklist_service,node_voice_router toneAmber
class node_ingest_runner,node_ingest,node_retrieval,node_embeddings toneMint
class node_staff_web,node_insights_web,node_handoff,node_insights toneRose
class node_database,node_gemini,node_elevenlabs,node_auth0,node_newcomer,node_staff_user,node_official_sources toneIndigo
```

## Components

### Newcomer experience

- [Localized web app](https://github.com/kamalchahal7/arrive/tree/main/frontend/src/app/%5Blocale%5D): `frontend/src/app/[locale]`
- [Checklist and programs](https://github.com/kamalchahal7/arrive/blob/main/frontend/src/app/%5Blocale%5D/(app)/roadmap/page.tsx): `frontend/src/app/[locale]/(app)/roadmap/page.tsx`
- [Voice experience](https://github.com/kamalchahal7/arrive/blob/main/frontend/src/components/VoiceAssistant.tsx): `frontend/src/components/VoiceAssistant.tsx`

### API and domain

- [FastAPI application](https://github.com/kamalchahal7/arrive/blob/main/backend/app/main.py): `backend/app/main.py`
- [Ask endpoint](https://github.com/kamalchahal7/arrive/blob/main/backend/app/routers/ask.py): `backend/app/routers/ask.py`
- [Answer service](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/ask.py): `backend/app/services/ask.py`
- [Checklist endpoints](https://github.com/kamalchahal7/arrive/blob/main/backend/app/routers/checklist.py): `backend/app/routers/checklist.py`
- [Household checklist](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/checklist.py): `backend/app/services/checklist.py`
- [Voice tools](https://github.com/kamalchahal7/arrive/blob/main/backend/app/routers/voice.py): `backend/app/routers/voice.py`

### Official knowledge

- [Ingestion scheduler](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/ingestion_runner.py): `backend/app/services/ingestion_runner.py`
- [Source ingestion](https://github.com/kamalchahal7/arrive/blob/main/ingestion/ingest.py): `ingestion/ingest.py`
- [Source retrieval](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/retrieval.py): `backend/app/services/retrieval.py`
- [Embedding helpers](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`

### Staff workflows

- [Staff portal](https://github.com/kamalchahal7/arrive/blob/main/frontend/src/app/(staff)/worker/page.tsx): `frontend/src/app/(staff)/worker/page.tsx`
- [Insights dashboard](https://github.com/kamalchahal7/arrive/blob/main/frontend/src/app/(staff)/insights/page.tsx): `frontend/src/app/(staff)/insights/page.tsx`
- [Worker handoffs](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/handoff.py): `backend/app/services/handoff.py`
- [Needs analytics](https://github.com/kamalchahal7/arrive/blob/main/backend/app/services/insights.py): `backend/app/services/insights.py`

### External services

- **Tiger Data**
- **Gemini**
- **ElevenLabs**
- **Auth0**

### Other components

- **Newcomer**
- **Settlement staff**
- **Official web pages**

## Connections

- Newcomer → Localized web app: uses (evidence: `README.md`)
- Localized web app → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Ask endpoint: routes (evidence: `backend/app/main.py`)
- Ask endpoint → Answer service: calls (evidence: `backend/app/routers/ask.py`)
- Answer service → Source retrieval: retrieves sources
- Source retrieval → Embedding helpers: embeds query (evidence: `backend/app/services/retrieval.py`)
- Embedding helpers → Gemini: requests vectors (evidence: `backend/app/services/embeddings.py`)
- Source retrieval → Tiger Data: searches passages (evidence: `README.md`)
- Answer service → Gemini: generates answers (evidence: `README.md`)
- Localized web app → Checklist and programs: opens (evidence: `README.md`)
- Checklist and programs → FastAPI application: calls API
- FastAPI application → Checklist endpoints: routes (evidence: `backend/app/main.py`)
- Checklist endpoints → Household checklist: builds checklist (evidence: `backend/app/routers/checklist.py`)
- Checklist endpoints → Tiger Data: reads progress
- FastAPI application → Ingestion scheduler: schedules ingestion (evidence: `backend/app/main.py`)
- Ingestion scheduler → Source ingestion: runs (evidence: `backend/app/services/ingestion_runner.py`)
- Official web pages → Source ingestion: provides pages (evidence: `ingestion/ingest.py`)
- Source ingestion → Embedding helpers: embeds chunks (evidence: `ingestion/ingest.py`)
- Source ingestion → Tiger Data: writes chunks (evidence: `ingestion/ingest.py`)
- Voice experience → ElevenLabs: connects agent (evidence: `README.md`)
- ElevenLabs → Voice tools: calls tools (evidence: `README.md`)
- FastAPI application → Voice tools: routes (evidence: `backend/app/main.py`)
- Voice tools → Answer service: calls (evidence: `backend/app/routers/voice.py`)
- Settlement staff → Staff portal: uses (evidence: `README.md`)
- Settlement staff → Insights dashboard: uses (evidence: `README.md`)
- Staff portal → Auth0: authenticates (evidence: `README.md`)
- Staff portal → FastAPI application: calls API (evidence: `README.md`)
- Insights dashboard → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Worker handoffs: routes handoffs
- FastAPI application → Needs analytics: routes analytics
- Needs analytics → Tiger Data: aggregates activity (evidence: `README.md`)
