# iamenibrahim/last-mile architecture

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

- Interactive diagram: https://gitdiagram.com/iamenibrahim/last-mile
- Repository: https://github.com/iamenibrahim/last-mile

## Overview

Last-Mile is a disaster-assistance navigator that turns a person’s location and needs into a cited, signed Disaster Action Packet, then offers ways to verify, save, resume, and deliver it. The main journey runs from browser intake through API navigation and deterministic matching against reviewed assistance data, into packet construction and verification, and finally to web, SMS, voice, print, or offline use. The README documents these capabilities; sampled source confirms the API boundary, navigation call, continuity and channel integrations, and safety checks. Some unsampled subsystem wiring is therefore shown only where documented.

Main entry points: [`api/main.py`](https://github.com/iamenibrahim/last-mile/blob/main/api/main.py) (FastAPI application), [`grounded/actions.py`](https://github.com/iamenibrahim/last-mile/blob/main/grounded/actions.py) (Packet construction), [`grounded/navigator.py`](https://github.com/iamenibrahim/last-mile/blob/main/grounded/navigator.py) (Need-based matching), [`api/providers/azure_sms.py`](https://github.com/iamenibrahim/last-mile/blob/main/api/providers/azure_sms.py) (SMS delivery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["Intake and Matching"]
  node_browser["Browser experience<br/>[assist.js]"]
  node_api["FastAPI application<br/>[main.py]"]
  node_navigator["Need-based matching<br/>[navigator.py]"]
  node_geo["Location resolution<br/>[geo.py]"]
  node_areas["County and areas<br/>[areas.py]"]
end

subgraph group_packet["Packet and Trust"]
  node_packetbuilder["Packet construction<br/>[actions.py]"]
  node_entities["Locked facts<br/>[entities.py]"]
  node_transform["Plain-language transform<br/>[transform.py]"]
  node_verify["Packet verification<br/>[verify.py]"]
  node_signing["Packet signing<br/>[manifest.py]"]
end

subgraph group_delivery["Channels and Continuity"]
  node_continuity[("Recovery code store<br/>[store.py]")]
  node_sms["SMS delivery<br/>[azure_sms.py]"]
  node_voice["Voice calls<br/>[azure_voice.py]"]
  node_offline["Offline packet<br/>[main.py]"]
end

subgraph group_integrations["Data and Providers"]
  node_sources["Reviewed source records<br/>[sources.py]"]
  node_fema["FEMA program data<br/>[fema.py]"]
  node_quotes["Exact quote search<br/>[quote_search.py]"]
  node_providers["Language and safety providers<br/>[azure_providers.py]"]
end

node_person(("Person seeking aid"))
node_government(("Government and nonprofit sources"))
node_azure(("Azure services"))
node_human(("Human help"))

node_person -->|"provides needs"| node_browser
node_browser -->|"sends answers"| node_api
node_api -->|"requests matching"| node_navigator
node_api -->|"resolves location"| node_geo
node_api -->|"disambiguates county"| node_areas
node_navigator -->|"matches reviewed data"| node_sources
node_sources -->|"curates records"| node_government
node_navigator -->|"uses program data"| node_fema
node_navigator -->|"builds recommendations"| node_packetbuilder
node_packetbuilder -->|"retrieves evidence"| node_quotes
node_quotes -->|"locates exact passages"| node_sources
node_packetbuilder -->|"locks critical facts"| node_entities
node_packetbuilder -->|"prepares channel text"| node_transform
node_transform -.->|"requests transformation"| node_providers
node_providers -.->|"uses configured services"| node_azure
node_packetbuilder -->|"signs packet"| node_signing
node_api -->|"verifies packet"| node_verify
node_api -->|"saves or resumes"| node_continuity
node_api -->|"creates offline packet"| node_offline
node_offline -->|"checks packet"| node_verify
node_api -->|"sends with consent"| node_sms
node_sms -->|"loads packet"| node_continuity
node_sms -.->|"dispatches message"| node_azure
node_api -->|"starts verified call"| node_voice
node_voice -.->|"places call"| node_azure
node_api -->|"offers escalation"| node_human

click node_browser "https://github.com/iamenibrahim/last-mile/blob/main/web/grounded/assist.js"
click node_api "https://github.com/iamenibrahim/last-mile/blob/main/api/main.py"
click node_navigator "https://github.com/iamenibrahim/last-mile/blob/main/grounded/navigator.py"
click node_geo "https://github.com/iamenibrahim/last-mile/blob/main/grounded/geo.py"
click node_areas "https://github.com/iamenibrahim/last-mile/blob/main/grounded/areas.py"
click node_sources "https://github.com/iamenibrahim/last-mile/blob/main/grounded/sources.py"
click node_fema "https://github.com/iamenibrahim/last-mile/blob/main/grounded/fema.py"
click node_quotes "https://github.com/iamenibrahim/last-mile/blob/main/grounded/quote_search.py"
click node_packetbuilder "https://github.com/iamenibrahim/last-mile/blob/main/grounded/actions.py"
click node_entities "https://github.com/iamenibrahim/last-mile/blob/main/grounded/entities.py"
click node_transform "https://github.com/iamenibrahim/last-mile/blob/main/grounded/transform.py"
click node_verify "https://github.com/iamenibrahim/last-mile/blob/main/grounded/verify.py"
click node_signing "https://github.com/iamenibrahim/last-mile/blob/main/grounded/manifest.py"
click node_continuity "https://github.com/iamenibrahim/last-mile/blob/main/grounded/store.py"
click node_sms "https://github.com/iamenibrahim/last-mile/blob/main/api/providers/azure_sms.py"
click node_voice "https://github.com/iamenibrahim/last-mile/blob/main/api/providers/azure_voice.py"
click node_offline "https://github.com/iamenibrahim/last-mile/blob/main/api/main.py"
click node_providers "https://github.com/iamenibrahim/last-mile/blob/main/grounded/providers/azure_providers.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_browser,node_api,node_navigator,node_geo,node_areas toneBlue
class node_packetbuilder,node_entities,node_transform,node_verify,node_signing toneAmber
class node_continuity,node_sms,node_voice,node_offline toneMint
class node_sources,node_fema,node_quotes,node_providers toneRose
class node_person,node_government,node_azure,node_human toneIndigo
```

## Components

### Intake and Matching

- [Browser experience](https://github.com/iamenibrahim/last-mile/blob/main/web/grounded/assist.js): `web/grounded/assist.js`
- [FastAPI application](https://github.com/iamenibrahim/last-mile/blob/main/api/main.py): `api/main.py`
- [Need-based matching](https://github.com/iamenibrahim/last-mile/blob/main/grounded/navigator.py): `grounded/navigator.py`
- [Location resolution](https://github.com/iamenibrahim/last-mile/blob/main/grounded/geo.py): `grounded/geo.py`
- [County and areas](https://github.com/iamenibrahim/last-mile/blob/main/grounded/areas.py): `grounded/areas.py`

### Packet and Trust

- [Packet construction](https://github.com/iamenibrahim/last-mile/blob/main/grounded/actions.py): `grounded/actions.py`
- [Locked facts](https://github.com/iamenibrahim/last-mile/blob/main/grounded/entities.py): `grounded/entities.py`
- [Plain-language transform](https://github.com/iamenibrahim/last-mile/blob/main/grounded/transform.py): `grounded/transform.py`
- [Packet verification](https://github.com/iamenibrahim/last-mile/blob/main/grounded/verify.py): `grounded/verify.py`
- [Packet signing](https://github.com/iamenibrahim/last-mile/blob/main/grounded/manifest.py): `grounded/manifest.py`

### Channels and Continuity

- [Recovery code store](https://github.com/iamenibrahim/last-mile/blob/main/grounded/store.py): `grounded/store.py`
- [SMS delivery](https://github.com/iamenibrahim/last-mile/blob/main/api/providers/azure_sms.py): `api/providers/azure_sms.py`
- [Voice calls](https://github.com/iamenibrahim/last-mile/blob/main/api/providers/azure_voice.py): `api/providers/azure_voice.py`
- [Offline packet](https://github.com/iamenibrahim/last-mile/blob/main/api/main.py): `api/main.py`

### Data and Providers

- [Reviewed source records](https://github.com/iamenibrahim/last-mile/blob/main/grounded/sources.py): `grounded/sources.py`
- [FEMA program data](https://github.com/iamenibrahim/last-mile/blob/main/grounded/fema.py): `grounded/fema.py`
- [Exact quote search](https://github.com/iamenibrahim/last-mile/blob/main/grounded/quote_search.py): `grounded/quote_search.py`
- [Language and safety providers](https://github.com/iamenibrahim/last-mile/blob/main/grounded/providers/azure_providers.py): `grounded/providers/azure_providers.py`

### Other components

- **Person seeking aid**
- **Government and nonprofit sources**
- **Azure services**
- **Human help**

## Connections

- Person seeking aid → Browser experience: provides needs
- Browser experience → FastAPI application: sends answers
- FastAPI application → Need-based matching: requests matching
- FastAPI application → Location resolution: resolves location
- FastAPI application → County and areas: disambiguates county
- Need-based matching → Reviewed source records: matches reviewed data
- Reviewed source records → Government and nonprofit sources: curates records
- Need-based matching → FEMA program data: uses program data
- Need-based matching → Packet construction: builds recommendations
- Packet construction → Exact quote search: retrieves evidence
- Exact quote search → Reviewed source records: locates exact passages
- Packet construction → Locked facts: locks critical facts
- Packet construction → Plain-language transform: prepares channel text
- Plain-language transform → Language and safety providers: requests transformation
- Language and safety providers → Azure services: uses configured services
- Packet construction → Packet signing: signs packet
- FastAPI application → Packet verification: verifies packet
- FastAPI application → Recovery code store: saves or resumes
- FastAPI application → Offline packet: creates offline packet
- Offline packet → Packet verification: checks packet
- FastAPI application → SMS delivery: sends with consent
- SMS delivery → Recovery code store: loads packet
- SMS delivery → Azure services: dispatches message
- FastAPI application → Voice calls: starts verified call
- Voice calls → Azure services: places call
- FastAPI application → Human help: offers escalation