# ilyassbelayachi/smart-immigration architecture

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

- Interactive diagram: https://gitdiagram.com/ilyassbelayachi/smart-immigration
- Repository: https://github.com/ilyassbelayachi/smart-immigration

## Overview

Smart Immigration Process is a preparation assistant for Canadian study-permit applicants; it provides sourced information and indicative rule checks, not decisions or submissions to authorities. The main workflow is an applicant request through the API: questions get lexical retrieval and either a cited answer or abstention; profiles get rule-based verdicts and, for checklist requests, document-preparation items. A separate ingestion command collects official pages for a corpus. The map reflects sampled source and README evidence; the demo UI and ingestion destinations are documented, but not all runtime details are sampled.

Main entry points: [`src/smart_immigration/knowledge/routes.py`](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/routes.py) (Knowledge routes), [`src/smart_immigration/dossier/routes.py`](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/dossier/routes.py) (Dossier routes), [`src/smart_immigration/api.py`](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/api.py) (FastAPI application), [`src/smart_immigration/knowledge/retrieval.py`](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/retrieval.py) (Lexical retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_knowledge["Knowledge assistance"]
  node_knowledge_routes["Knowledge routes<br/>[routes.py]"]
  node_retrieval["Lexical retrieval<br/>[retrieval.py]"]
  node_qa["Sourced answers<br/>[qa.py]"]
  node_seed[("Seed corpus<br/>[seed_chunks.jsonl]")]
  node_ingest["Page ingestion<br/>[ingest.py]"]
  node_source_config["Page source list<br/>[sources.yaml]"]
end

subgraph group_dossier["Applicant dossier"]
  node_dossier_routes["Dossier routes<br/>[routes.py]"]
  node_rules_engine["Permit rule engine<br/>[rules.py]"]
  node_rulebook["Permit rules"]
  node_checklist["Preparation checklist<br/>[checklist.py]"]
end

subgraph group_api["API and contracts"]
  node_api_app["FastAPI application<br/>[api.py]"]
  node_demo_ui["Demo interface"]
  node_contracts["Request and result schemas<br/>[schemas.py]"]
end

node_applicant(("Applicant"))
node_ircc["Official IRCC pages"]

node_applicant -->|"uses"| node_demo_ui
node_demo_ui -.->|"requests"| node_api_app
node_applicant -->|"submits profile or question"| node_api_app
node_api_app -->|"mounts routes"| node_knowledge_routes
node_api_app -->|"mounts routes"| node_dossier_routes
node_knowledge_routes -->|"uses schemas"| node_contracts
node_dossier_routes -->|"uses schemas"| node_contracts
node_knowledge_routes -->|"loads index"| node_retrieval
node_knowledge_routes -->|"requests answer"| node_qa
node_retrieval -->|"loads fallback corpus"| node_seed
node_qa -->|"searches passages"| node_retrieval
node_ingest -->|"reads sources"| node_source_config
node_ingest -->|"fetches pages"| node_ircc
node_dossier_routes -->|"assesses profile"| node_rules_engine
node_rules_engine -->|"loads rules"| node_rulebook
node_dossier_routes -->|"builds checklist"| node_checklist

click node_api_app "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/api.py"
click node_demo_ui "https://github.com/ilyassbelayachi/smart-immigration/tree/main/frontend"
click node_contracts "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/schemas.py"
click node_knowledge_routes "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/routes.py"
click node_retrieval "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/retrieval.py"
click node_qa "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/qa.py"
click node_seed "https://github.com/ilyassbelayachi/smart-immigration/blob/main/data/seed/seed_chunks.jsonl"
click node_ingest "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/ingest.py"
click node_source_config "https://github.com/ilyassbelayachi/smart-immigration/blob/main/data/sources.yaml"
click node_dossier_routes "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/dossier/routes.py"
click node_rules_engine "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/dossier/rules.py"
click node_rulebook "https://github.com/ilyassbelayachi/smart-immigration/blob/main/rules/study_permit_ca.yaml"
click node_checklist "https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/dossier/checklist.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_knowledge_routes,node_retrieval,node_qa,node_seed,node_ingest,node_source_config toneBlue
class node_dossier_routes,node_rules_engine,node_rulebook,node_checklist toneAmber
class node_api_app,node_demo_ui,node_contracts toneMint
class node_applicant,node_ircc toneIndigo
```

## Components

### Knowledge assistance

- [Knowledge routes](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/routes.py): `src/smart_immigration/knowledge/routes.py`
- [Lexical retrieval](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/retrieval.py): `src/smart_immigration/knowledge/retrieval.py`
- [Sourced answers](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/qa.py): `src/smart_immigration/knowledge/qa.py`
- [Seed corpus](https://github.com/ilyassbelayachi/smart-immigration/blob/main/data/seed/seed_chunks.jsonl): `data/seed/seed_chunks.jsonl`
- [Page ingestion](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/knowledge/ingest.py): `src/smart_immigration/knowledge/ingest.py`
- [Page source list](https://github.com/ilyassbelayachi/smart-immigration/blob/main/data/sources.yaml): `data/sources.yaml`

### Applicant dossier

- [Dossier routes](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/dossier/routes.py): `src/smart_immigration/dossier/routes.py`
- [Permit rule engine](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/dossier/rules.py): `src/smart_immigration/dossier/rules.py`
- [Permit rules](https://github.com/ilyassbelayachi/smart-immigration/blob/main/rules/study_permit_ca.yaml): `rules/study_permit_ca.yaml`
- [Preparation checklist](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/dossier/checklist.py): `src/smart_immigration/dossier/checklist.py`

### API and contracts

- [FastAPI application](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/api.py): `src/smart_immigration/api.py`
- [Demo interface](https://github.com/ilyassbelayachi/smart-immigration/tree/main/frontend): `frontend`
- [Request and result schemas](https://github.com/ilyassbelayachi/smart-immigration/blob/main/src/smart_immigration/schemas.py): `src/smart_immigration/schemas.py`

### Other components

- **Applicant**
- **Official IRCC pages**

## Connections

- Applicant → Demo interface: uses (evidence: `README.md`)
- Demo interface → FastAPI application: requests
- Applicant → FastAPI application: submits profile or question (evidence: `README.md`)
- FastAPI application → Knowledge routes: mounts routes (evidence: `src/smart_immigration/api.py`)
- FastAPI application → Dossier routes: mounts routes (evidence: `src/smart_immigration/api.py`)
- Knowledge routes → Request and result schemas: uses schemas (evidence: `src/smart_immigration/knowledge/routes.py`)
- Dossier routes → Request and result schemas: uses schemas (evidence: `src/smart_immigration/dossier/routes.py`)
- Knowledge routes → Lexical retrieval: loads index (evidence: `src/smart_immigration/knowledge/routes.py`)
- Knowledge routes → Sourced answers: requests answer (evidence: `src/smart_immigration/knowledge/routes.py`)
- Lexical retrieval → Seed corpus: loads fallback corpus (evidence: `src/smart_immigration/knowledge/retrieval.py`)
- Sourced answers → Lexical retrieval: searches passages (evidence: `src/smart_immigration/knowledge/qa.py`)
- Page ingestion → Page source list: reads sources (evidence: `src/smart_immigration/knowledge/ingest.py`)
- Page ingestion → Official IRCC pages: fetches pages (evidence: `src/smart_immigration/knowledge/ingest.py`)
- Dossier routes → Permit rule engine: assesses profile (evidence: `src/smart_immigration/dossier/routes.py`)
- Permit rule engine → Permit rules: loads rules (evidence: `src/smart_immigration/dossier/rules.py`)
- Dossier routes → Preparation checklist: builds checklist (evidence: `src/smart_immigration/dossier/routes.py`)