# swiftkimani/kaziscout architecture

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

- Interactive diagram: https://gitdiagram.com/swiftkimani/kaziscout
- Repository: https://github.com/swiftkimani/kaziscout

## Overview

KaziScout is a local-first job-search agent: a user builds a profile, scans job sources, reviews and scores postings, then tracks applications and prepares materials while submitting applications themselves. The browser and terminal are documented entry points; this graph focuses on the browser-to-result path and the server services behind it. The README describes the provider, storage, scoring, and optional integrations; some subsystem details are unsampled, so only documented or indexed relationships are connected.

Main entry points: [`server/src/routes/v1.ts`](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/routes/v1.ts) (HTTP routes), [`server/src/app.ts`](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/app.ts) (Service wiring), [`web/src/App.tsx`](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/App.tsx) (Browser app), [`web/src/api/queries.ts`](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/api/queries.ts) (API queries)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Browser app<br/>[App.tsx]"]
  node_jobui["Jobs and boards<br/>[JobsPage.tsx]"]
  node_trackerui["Application tracker<br/>[TrackerPage.tsx]"]
  node_profileui["Profile and CV<br/>[ProfileForm.tsx]"]
  node_apiqueries["API queries<br/>[queries.ts]"]
  node_httpclient["API client<br/>[client.ts]"]
  node_boardsui["Board directory<br/>[BoardsPage.tsx]"]
  node_extractui["Markdown tool<br/>[ExtractPage.tsx]"]
end

subgraph group_api["HTTP application"]
  node_routes["HTTP routes<br/>[v1.ts]"]
  node_appwire["Service wiring<br/>[app.ts]"]
  node_database[("SQLite database<br/>[client.ts]")]
end

subgraph group_discovery["Job discovery"]
  node_scan["Board scanning<br/>[scan.ts]"]
  node_registry["Source registry<br/>[registry.ts]"]
  node_providers["Board providers<br/>[index.ts]"]
  node_jobsrepo["Jobs storage<br/>[jobs.ts]"]
end

subgraph group_assessment["Profile and assessment"]
  node_profile["CV import and profile<br/>[cv-import.ts]"]
  node_evaluation["Job evaluation<br/>[evaluation.ts]"]
  node_heuristic["Fit scoring<br/>[heuristic.ts]"]
  node_ai["AI model client<br/>[client.ts]"]
end

subgraph group_outcomes["Application tools"]
  node_markdown["Page to Markdown<br/>[markdown.ts]"]
  node_documents["Application documents<br/>[documents.ts]"]
  node_apply["Application assistance<br/>[apply.ts]"]
  node_applications["Application tracking<br/>[applications.ts]"]
end

node_person(("Job seeker"))
node_employers(("Boards and employers"))
node_ai_service(("Configured AI service"))

node_person -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_jobui
node_webapp -->|"routes to"| node_boardsui
node_webapp -->|"routes to"| node_trackerui
node_webapp -->|"routes to"| node_profileui
node_webapp -->|"routes to"| node_extractui
node_jobui -->|"requests data"| node_apiqueries
node_trackerui -->|"requests data"| node_apiqueries
node_profileui -->|"requests data"| node_apiqueries
node_boardsui -->|"requests data"| node_apiqueries
node_extractui -->|"requests data"| node_apiqueries
node_apiqueries -->|"calls"| node_httpclient
node_httpclient -->|"sends JSON"| node_routes
node_routes -->|"dispatches"| node_scan
node_routes -->|"dispatches"| node_evaluation
node_routes -->|"dispatches"| node_profile
node_routes -->|"dispatches"| node_markdown
node_routes -->|"dispatches"| node_documents
node_routes -->|"dispatches"| node_apply
node_appwire -->|"registers"| node_routes
node_appwire -->|"wires"| node_scan
node_appwire -->|"wires"| node_evaluation
node_appwire -->|"wires"| node_markdown
node_appwire -->|"wires"| node_documents
node_appwire -->|"wires"| node_apply
node_scan -->|"uses sources"| node_registry
node_scan -->|"dispatches scans"| node_providers
node_scan -->|"stores postings"| node_jobsrepo
node_providers -->|"fetches postings"| node_employers
node_evaluation -->|"scores with"| node_heuristic
node_evaluation -.->|"optionally assesses"| node_ai
node_ai -->|"requests assessment"| node_ai_service
node_jobsrepo -->|"reads and writes"| node_database
node_applications -->|"reads and writes"| node_database
node_routes -->|"dispatches tracking"| node_applications
node_apply -.->|"records progress"| node_applications
node_person -.->|"chooses postings"| node_employers

click node_webapp "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/App.tsx"
click node_jobui "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/jobs/JobsPage.tsx"
click node_trackerui "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/tracker/TrackerPage.tsx"
click node_profileui "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/profile/ProfileForm.tsx"
click node_apiqueries "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/api/queries.ts"
click node_httpclient "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/api/client.ts"
click node_routes "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/routes/v1.ts"
click node_appwire "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/app.ts"
click node_scan "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/scan.ts"
click node_registry "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/boards/registry.ts"
click node_providers "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/providers/index.ts"
click node_jobsrepo "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/repositories/jobs.ts"
click node_database "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/db/client.ts"
click node_profile "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/cv-import.ts"
click node_evaluation "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/evaluation.ts"
click node_heuristic "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/scoring/heuristic.ts"
click node_ai "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/ai/client.ts"
click node_markdown "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/markdown.ts"
click node_documents "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/documents.ts"
click node_apply "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/apply.ts"
click node_applications "https://github.com/swiftkimani/kaziscout/blob/dev/server/src/repositories/applications.ts"
click node_boardsui "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/boards/BoardsPage.tsx"
click node_extractui "https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/extract/ExtractPage.tsx"

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_webapp,node_jobui,node_trackerui,node_profileui,node_apiqueries,node_httpclient,node_boardsui,node_extractui toneBlue
class node_routes,node_appwire,node_database toneAmber
class node_scan,node_registry,node_providers,node_jobsrepo toneMint
class node_profile,node_evaluation,node_heuristic,node_ai toneRose
class node_markdown,node_documents,node_apply,node_applications,node_person,node_employers,node_ai_service toneIndigo
```

## Components

### Web experience

- [Browser app](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/App.tsx): `web/src/App.tsx`
- [Jobs and boards](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/jobs/JobsPage.tsx): `web/src/features/jobs/JobsPage.tsx`
- [Application tracker](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/tracker/TrackerPage.tsx): `web/src/features/tracker/TrackerPage.tsx`
- [Profile and CV](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/profile/ProfileForm.tsx): `web/src/features/profile/ProfileForm.tsx`
- [API queries](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/api/queries.ts): `web/src/api/queries.ts`
- [API client](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/api/client.ts): `web/src/api/client.ts`
- [Board directory](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/boards/BoardsPage.tsx): `web/src/features/boards/BoardsPage.tsx`
- [Markdown tool](https://github.com/swiftkimani/kaziscout/blob/dev/web/src/features/extract/ExtractPage.tsx): `web/src/features/extract/ExtractPage.tsx`

### HTTP application

- [HTTP routes](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/routes/v1.ts): `server/src/routes/v1.ts`
- [Service wiring](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/app.ts): `server/src/app.ts`
- [SQLite database](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/db/client.ts): `server/src/db/client.ts`

### Job discovery

- [Board scanning](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/scan.ts): `server/src/services/scan.ts`
- [Source registry](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/boards/registry.ts): `server/src/boards/registry.ts`
- [Board providers](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/providers/index.ts): `server/src/providers/index.ts`
- [Jobs storage](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/repositories/jobs.ts): `server/src/repositories/jobs.ts`

### Profile and assessment

- [CV import and profile](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/cv-import.ts): `server/src/services/cv-import.ts`
- [Job evaluation](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/evaluation.ts): `server/src/services/evaluation.ts`
- [Fit scoring](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/scoring/heuristic.ts): `server/src/scoring/heuristic.ts`
- [AI model client](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/ai/client.ts): `server/src/ai/client.ts`

### Application tools

- [Page to Markdown](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/markdown.ts): `server/src/services/markdown.ts`
- [Application documents](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/documents.ts): `server/src/services/documents.ts`
- [Application assistance](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/services/apply.ts): `server/src/services/apply.ts`
- [Application tracking](https://github.com/swiftkimani/kaziscout/blob/dev/server/src/repositories/applications.ts): `server/src/repositories/applications.ts`

### Other components

- **Job seeker**
- **Boards and employers**
- **Configured AI service**

## Connections

- Job seeker → Browser app: uses (evidence: `web/src/App.tsx`)
- Browser app → Jobs and boards: routes to (evidence: `web/src/App.tsx`)
- Browser app → Board directory: routes to (evidence: `web/src/App.tsx`)
- Browser app → Application tracker: routes to (evidence: `web/src/App.tsx`)
- Browser app → Profile and CV: routes to (evidence: `web/src/App.tsx`)
- Browser app → Markdown tool: routes to (evidence: `web/src/App.tsx`)
- Jobs and boards → API queries: requests data (evidence: `web/src/api/queries.ts`)
- Application tracker → API queries: requests data (evidence: `web/src/api/queries.ts`)
- Profile and CV → API queries: requests data (evidence: `web/src/api/queries.ts`)
- Board directory → API queries: requests data (evidence: `web/src/api/queries.ts`)
- Markdown tool → API queries: requests data (evidence: `web/src/api/queries.ts`)
- API queries → API client: calls (evidence: `web/src/api/queries.ts`)
- API client → HTTP routes: sends JSON (evidence: `README.md`)
- HTTP routes → Board scanning: dispatches (evidence: `server/src/routes/v1.ts`)
- HTTP routes → Job evaluation: dispatches (evidence: `server/src/routes/v1.ts`)
- HTTP routes → CV import and profile: dispatches (evidence: `server/src/routes/v1.ts`)
- HTTP routes → Page to Markdown: dispatches (evidence: `server/src/routes/v1.ts`)
- HTTP routes → Application documents: dispatches (evidence: `server/src/routes/v1.ts`)
- HTTP routes → Application assistance: dispatches (evidence: `server/src/routes/v1.ts`)
- Service wiring → HTTP routes: registers (evidence: `server/src/app.ts`)
- Service wiring → Board scanning: wires (evidence: `server/src/app.ts`)
- Service wiring → Job evaluation: wires (evidence: `server/src/app.ts`)
- Service wiring → Page to Markdown: wires (evidence: `server/src/app.ts`)
- Service wiring → Application documents: wires (evidence: `server/src/app.ts`)
- Service wiring → Application assistance: wires (evidence: `server/src/app.ts`)
- Board scanning → Source registry: uses sources (evidence: `server/src/services/scan.ts`)
- Board scanning → Board providers: dispatches scans (evidence: `server/src/services/scan.ts`)
- Board scanning → Jobs storage: stores postings (evidence: `server/src/services/scan.ts`)
- Board providers → Boards and employers: fetches postings (evidence: `README.md`)
- Job evaluation → Fit scoring: scores with (evidence: `server/src/app.ts`)
- Job evaluation → AI model client: optionally assesses (evidence: `server/src/app.ts`)
- AI model client → Configured AI service: requests assessment (evidence: `README.md`)
- Jobs storage → SQLite database: reads and writes (evidence: `server/src/repositories/jobs.ts`)
- Application tracking → SQLite database: reads and writes (evidence: `server/src/repositories/applications.ts`)
- HTTP routes → Application tracking: dispatches tracking (evidence: `server/src/routes/v1.ts`)
- Application assistance → Application tracking: records progress
- Job seeker → Boards and employers: chooses postings
