# nerdywhiskers/catabull architecture

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

## Overview

CataBull is a local-first job-search dashboard and CLI. The main user journey is to configure a profile and target companies, discover and evaluate postings, manage promising roles in a pipeline, then generate tailored application materials and track applications. The graph also shows the dashboard/API boundary, local workspace persistence, agent-backed workflows, and documented health monitoring and terminal capabilities. Some route and scan wiring is supported by the SOURCE INDEX or README rather than full excerpts; those evidence limits are reflected in the citations.

Main entry points: [`dashboard-web/routes/scan-deep.mjs`](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/scan-deep.mjs) (Deep scan workflow), [`dashboard-web/routes/applications.mjs`](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/applications.mjs) (Application actions), [`dashboard-web/routes/onboarding.mjs`](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/onboarding.mjs) (Company onboarding), [`dashboard-web/lib/writers.mjs`](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/lib/writers.mjs) (Workspace data writers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Dashboard"]
  node_webapp["Dashboard UI<br/>[app.mjs]"]
  node_views["Search and pipeline views"]
  node_api["Dashboard API client<br/>[api.mjs]"]
end

subgraph group_discovery["Discovery"]
  node_onboarding["Company onboarding<br/>[onboarding.mjs]"]
  node_scanroute["Deep scan workflow<br/>[scan-deep.mjs]"]
  node_level3["Deep discovery<br/>[level3.mjs]"]
  node_websearch["Web search providers<br/>[websearch.mjs]"]
  node_ats["ATS providers<br/>[index.mjs]"]
  node_relevance["Role relevance scoring<br/>[relevance.mjs]"]
  node_health["Portal health monitoring<br/>[health.mjs]"]
end

subgraph group_applications["Application workflow"]
  node_identity["Role identity matching<br/>[role-identity.mjs]"]
  node_applicationroutes["Application actions<br/>[applications.mjs]"]
  node_tailoring["Tailored materials<br/>[tailor.mjs]"]
end

subgraph group_workspace["Local workspace"]
  node_tracker["Pipeline and application data<br/>[parsers.mjs]"]
  node_writers["Workspace data writers<br/>[writers.mjs]"]
  node_workspacefiles[("Local workspace files<br/>[workspace.mjs]")]
end

subgraph group_runtime["Runtime services"]
  node_server["Fastify server<br/>[server.mjs]"]
  node_routes["Dashboard routes"]
  node_agents["CLI agent sessions<br/>[agents.mjs]"]
  node_terminal["Integrated agent terminal<br/>[terminal.mjs]"]
end

node_user(("Job seeker"))

node_user -->|"uses"| node_webapp
node_webapp -->|"renders views"| node_views
node_views -.->|"requests data"| node_api
node_api -.->|"calls endpoints"| node_routes
node_server -->|"registers routes"| node_routes
node_routes -.->|"handles setup"| node_onboarding
node_onboarding -->|"tests selected agent"| node_agents
node_onboarding -->|"saves targets"| node_writers
node_user -->|"configures targets"| node_onboarding
node_scanroute -->|"runs deep scan"| node_level3
node_scanroute -->|"searches postings"| node_websearch
node_level3 -->|"queries web search"| node_websearch
node_scanroute -->|"uses ATS discovery"| node_ats
node_user -->|"starts discovery"| node_scanroute
node_scanroute -->|"scores roles"| node_relevance
node_applicationroutes -->|"reads pipeline"| node_tracker
node_applicationroutes -->|"deduplicates roles"| node_identity
node_applicationroutes -->|"runs tailoring agent"| node_agents
node_applicationroutes -->|"updates application data"| node_writers
node_tailoring -->|"reads profile and CV"| node_workspacefiles
node_tracker -->|"reads workspace files"| node_workspacefiles
node_writers -->|"writes workspace files"| node_workspacefiles
node_user -->|"checks portal health"| node_health
node_user -->|"opens agent terminal"| node_terminal
node_server -.->|"registers health routes"| node_health

click node_webapp "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/public/js/app.mjs"
click node_views "https://github.com/nerdywhiskers/catabull/tree/dev/dashboard-web/public/js/views"
click node_api "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/public/js/api.mjs"
click node_server "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/server.mjs"
click node_routes "https://github.com/nerdywhiskers/catabull/tree/dev/dashboard-web/routes"
click node_onboarding "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/onboarding.mjs"
click node_scanroute "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/scan-deep.mjs"
click node_level3 "https://github.com/nerdywhiskers/catabull/blob/dev/scan/level3.mjs"
click node_websearch "https://github.com/nerdywhiskers/catabull/blob/dev/scan/websearch.mjs"
click node_ats "https://github.com/nerdywhiskers/catabull/blob/dev/scan/providers/index.mjs"
click node_relevance "https://github.com/nerdywhiskers/catabull/blob/dev/lib/relevance.mjs"
click node_identity "https://github.com/nerdywhiskers/catabull/blob/dev/lib/role-identity.mjs"
click node_applicationroutes "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/applications.mjs"
click node_tailoring "https://github.com/nerdywhiskers/catabull/blob/dev/lib/tailor.mjs"
click node_agents "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/lib/agents.mjs"
click node_tracker "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/lib/parsers.mjs"
click node_writers "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/lib/writers.mjs"
click node_workspacefiles "https://github.com/nerdywhiskers/catabull/blob/dev/lib/workspace.mjs"
click node_health "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/health.mjs"
click node_terminal "https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/terminal.mjs"

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_views,node_api toneBlue
class node_onboarding,node_scanroute,node_level3,node_websearch,node_ats,node_relevance,node_health toneAmber
class node_identity,node_applicationroutes,node_tailoring toneMint
class node_tracker,node_writers,node_workspacefiles toneRose
class node_server,node_routes,node_agents,node_terminal,node_user toneIndigo
```

## Components

### Dashboard

- [Dashboard UI](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/public/js/app.mjs): `dashboard-web/public/js/app.mjs`
- [Search and pipeline views](https://github.com/nerdywhiskers/catabull/tree/dev/dashboard-web/public/js/views): `dashboard-web/public/js/views`
- [Dashboard API client](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/public/js/api.mjs): `dashboard-web/public/js/api.mjs`

### Discovery

- [Company onboarding](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/onboarding.mjs): `dashboard-web/routes/onboarding.mjs`
- [Deep scan workflow](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/scan-deep.mjs): `dashboard-web/routes/scan-deep.mjs`
- [Deep discovery](https://github.com/nerdywhiskers/catabull/blob/dev/scan/level3.mjs): `scan/level3.mjs`
- [Web search providers](https://github.com/nerdywhiskers/catabull/blob/dev/scan/websearch.mjs): `scan/websearch.mjs`
- [ATS providers](https://github.com/nerdywhiskers/catabull/blob/dev/scan/providers/index.mjs): `scan/providers/index.mjs`
- [Role relevance scoring](https://github.com/nerdywhiskers/catabull/blob/dev/lib/relevance.mjs): `lib/relevance.mjs`
- [Portal health monitoring](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/health.mjs): `dashboard-web/routes/health.mjs`

### Application workflow

- [Role identity matching](https://github.com/nerdywhiskers/catabull/blob/dev/lib/role-identity.mjs): `lib/role-identity.mjs`
- [Application actions](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/applications.mjs): `dashboard-web/routes/applications.mjs`
- [Tailored materials](https://github.com/nerdywhiskers/catabull/blob/dev/lib/tailor.mjs): `lib/tailor.mjs`

### Local workspace

- [Pipeline and application data](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/lib/parsers.mjs): `dashboard-web/lib/parsers.mjs`
- [Workspace data writers](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/lib/writers.mjs): `dashboard-web/lib/writers.mjs`
- [Local workspace files](https://github.com/nerdywhiskers/catabull/blob/dev/lib/workspace.mjs): `lib/workspace.mjs`

### Runtime services

- [Fastify server](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/server.mjs): `dashboard-web/server.mjs`
- [Dashboard routes](https://github.com/nerdywhiskers/catabull/tree/dev/dashboard-web/routes): `dashboard-web/routes`
- [CLI agent sessions](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/lib/agents.mjs): `dashboard-web/lib/agents.mjs`
- [Integrated agent terminal](https://github.com/nerdywhiskers/catabull/blob/dev/dashboard-web/routes/terminal.mjs): `dashboard-web/routes/terminal.mjs`

### Other components

- **Job seeker**

## Connections

- Job seeker → Dashboard UI: uses (evidence: `README.md`)
- Dashboard UI → Search and pipeline views: renders views (evidence: `dashboard-web/public/js/app.mjs`)
- Search and pipeline views → Dashboard API client: requests data (evidence: `dashboard-web/public/js/views/pipeline.mjs`)
- Dashboard API client → Dashboard routes: calls endpoints
- Fastify server → Dashboard routes: registers routes (evidence: `dashboard-web/server.mjs`)
- Dashboard routes → Company onboarding: handles setup (evidence: `dashboard-web/server.mjs`)
- Company onboarding → CLI agent sessions: tests selected agent (evidence: `dashboard-web/routes/onboarding.mjs`)
- Company onboarding → Workspace data writers: saves targets (evidence: `dashboard-web/routes/onboarding.mjs`)
- Job seeker → Company onboarding: configures targets (evidence: `README.md`)
- Deep scan workflow → Deep discovery: runs deep scan (evidence: `dashboard-web/routes/scan-deep.mjs`)
- Deep scan workflow → Web search providers: searches postings (evidence: `dashboard-web/routes/scan-deep.mjs`)
- Deep discovery → Web search providers: queries web search (evidence: `scan/level3.mjs`)
- Deep scan workflow → ATS providers: uses ATS discovery (evidence: `dashboard-web/routes/scan-deep.mjs`)
- Job seeker → Deep scan workflow: starts discovery (evidence: `README.md`)
- Deep scan workflow → Role relevance scoring: scores roles (evidence: `dashboard-web/routes/scan-deep.mjs`)
- Application actions → Pipeline and application data: reads pipeline (evidence: `dashboard-web/routes/applications.mjs`)
- Application actions → Role identity matching: deduplicates roles (evidence: `dashboard-web/routes/applications.mjs`)
- Application actions → CLI agent sessions: runs tailoring agent (evidence: `dashboard-web/routes/applications.mjs`)
- Application actions → Workspace data writers: updates application data (evidence: `dashboard-web/routes/applications.mjs`)
- Tailored materials → Local workspace files: reads profile and CV (evidence: `lib/tailor.mjs`)
- Pipeline and application data → Local workspace files: reads workspace files (evidence: `dashboard-web/lib/parsers.mjs`)
- Workspace data writers → Local workspace files: writes workspace files (evidence: `dashboard-web/lib/writers.mjs`)
- Job seeker → Portal health monitoring: checks portal health (evidence: `README.md`)
- Job seeker → Integrated agent terminal: opens agent terminal (evidence: `README.md`)
- Fastify server → Portal health monitoring: registers health routes (evidence: `dashboard-web/server.mjs`)
