# amirwebd3v/agentic-os architecture

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

- Interactive diagram: https://gitdiagram.com/amirwebd3v/agentic-os
- Repository: https://github.com/amirwebd3v/agentic-os

## Overview

Agentic OS is a local-first personal knowledge and automation app, with career workflows as its primary implemented product. The main user journey runs from the web UI through authenticated API routes into career processing, producing editable, reviewable drafts and tracked applications. Separate branches cover master-CV management, email triage, approvals, and dashboard/provider status. The graph follows documented and indexed relationships; unsampled mail and route internals are represented conservatively, so some links are omitted.

Main entry points: [`server/src/app.ts`](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/app.ts) (HTTP application), [`server/src/jobs/career-steps.ts`](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/jobs/career-steps.ts) (Career step jobs), [`server/src/llm/client.ts`](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/llm/client.ts) (LLM client and usage ledger), [`web/src/App.vue`](https://github.com/amirwebd3v/agentic-os/blob/main/web/src/App.vue) (Vue application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Web interface"]
  node_web["Vue application<br/>[App.vue]"]
  node_career_views["Career views"]
  node_mail_views["Email views<br/>[EmailView.vue]"]
  node_web_api["Web API client<br/>[api.ts]"]
end

subgraph group_career["Career workflows"]
  node_career_routes["Career API routes<br/>[career.ts]"]
  node_master_routes["Master CV routes<br/>[career-master.ts]"]
  node_career_steps["Career step jobs<br/>[career-steps.ts]"]
  node_intake["Posting intake<br/>[intake.ts]"]
  node_tailor["CV tailoring<br/>[tailor.ts]"]
  node_draft["Draft model<br/>[draft.ts]"]
  node_career_checks["Fit and verification<br/>[ats.ts]"]
  node_letter["Cover letter<br/>[letter.ts]"]
  node_render["Document rendering<br/>[career-render.ts]"]
end

subgraph group_mail["Email workflows"]
  node_mail_routes["Email API routes<br/>[email.ts]"]
  node_mail_processing["Mail analysis and triage<br/>[triage.ts]"]
  node_mail_sync["Gmail sync<br/>[sync.ts]"]
  node_oauth["Gmail authorization<br/>[oauth.ts]"]
  node_gmail["Gmail client<br/>[gmail.ts]"]
end

subgraph group_platform["Local platform"]
  node_server["HTTP application<br/>[app.ts]"]
  node_database[("Local SQLite database<br/>[index.ts]")]
  node_llm{{"Configured LLM provider"}}
  node_llm_client["LLM client and usage ledger<br/>[client.ts]"]
  node_vault[("Personal knowledge vault<br/>[writer.ts]")]
  node_dashboard["Dashboard and status<br/>[dashboard.ts]"]
  node_approvals["Approval workflow<br/>[apply.ts]"]
  node_decider["Local email decider<br/>[client.ts]"]
end

node_user(("Personal user"))
node_sidecar{{"Laya sidecar"}}

node_user -->|"uses"| node_web
node_web -->|"routes to"| node_career_views
node_web -->|"routes to"| node_mail_views
node_career_views -->|"requests data"| node_web_api
node_mail_views -->|"requests data"| node_web_api
node_web_api -->|"calls API"| node_server
node_server -->|"registers routes"| node_career_routes
node_server -->|"registers routes"| node_master_routes
node_server -->|"registers routes"| node_mail_routes
node_server -->|"registers routes"| node_dashboard
node_server -->|"registers routes"| node_approvals
node_career_routes -->|"dispatches jobs"| node_career_steps
node_career_steps -->|"extracts requirements"| node_intake
node_career_steps -->|"reads and saves drafts"| node_tailor
node_career_steps -->|"checks fit"| node_career_checks
node_career_steps -->|"writes letter"| node_letter
node_career_routes -->|"requests rendering"| node_render
node_render -->|"writes documents"| node_vault
node_intake -->|"extracts with"| node_llm_client
node_career_checks -->|"checks with"| node_llm_client
node_letter -->|"generates with"| node_llm_client
node_llm_client -->|"sends prompts"| node_llm
node_llm_client -->|"records usage"| node_database
node_master_routes -.->|"manages CV files"| node_vault
node_mail_routes -.->|"dispatches analysis"| node_mail_processing
node_mail_routes -.->|"starts sync"| node_mail_sync
node_mail_sync -.->|"uses client"| node_gmail
node_oauth -->|"uses client"| node_gmail
node_mail_processing -.->|"may consult"| node_decider
node_decider -.->|"requests decisions"| node_sidecar
node_dashboard -.->|"reads status"| node_database
node_approvals -.->|"applies approvals"| node_database

click node_web "https://github.com/amirwebd3v/agentic-os/blob/main/web/src/App.vue"
click node_career_views "https://github.com/amirwebd3v/agentic-os/blob/main/web/src/views/ApplicationView.vue"
click node_mail_views "https://github.com/amirwebd3v/agentic-os/blob/main/web/src/views/EmailView.vue"
click node_web_api "https://github.com/amirwebd3v/agentic-os/blob/main/web/src/api.ts"
click node_career_routes "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/career.ts"
click node_master_routes "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/career-master.ts"
click node_career_steps "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/jobs/career-steps.ts"
click node_intake "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/intake.ts"
click node_tailor "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/tailor.ts"
click node_draft "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/draft.ts"
click node_career_checks "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/ats.ts"
click node_letter "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/letter.ts"
click node_render "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/jobs/career-render.ts"
click node_mail_routes "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/email.ts"
click node_mail_processing "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/triage.ts"
click node_mail_sync "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/sync.ts"
click node_oauth "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/oauth.ts"
click node_gmail "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/gmail.ts"
click node_server "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/app.ts"
click node_database "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/db/index.ts"
click node_llm_client "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/llm/client.ts"
click node_vault "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/vault/writer.ts"
click node_dashboard "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/dashboard.ts"
click node_approvals "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/approvals/apply.ts"
click node_decider "https://github.com/amirwebd3v/agentic-os/blob/main/server/src/decider/client.ts"

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_career_views,node_mail_views,node_web_api,node_user toneBlue
class node_career_routes,node_master_routes,node_career_steps,node_intake,node_tailor,node_draft,node_career_checks,node_letter,node_render toneAmber
class node_mail_routes,node_mail_processing,node_mail_sync,node_oauth,node_gmail toneMint
class node_server,node_database,node_llm,node_llm_client,node_vault,node_dashboard,node_approvals,node_decider toneRose
class node_sidecar toneIndigo
```

## Components

### Web interface

- [Vue application](https://github.com/amirwebd3v/agentic-os/blob/main/web/src/App.vue): `web/src/App.vue`
- [Career views](https://github.com/amirwebd3v/agentic-os/blob/main/web/src/views/ApplicationView.vue): `web/src/views/ApplicationView.vue`
- [Email views](https://github.com/amirwebd3v/agentic-os/blob/main/web/src/views/EmailView.vue): `web/src/views/EmailView.vue`
- [Web API client](https://github.com/amirwebd3v/agentic-os/blob/main/web/src/api.ts): `web/src/api.ts`

### Career workflows

- [Career API routes](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/career.ts): `server/src/http/routes/career.ts`
- [Master CV routes](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/career-master.ts): `server/src/http/routes/career-master.ts`
- [Career step jobs](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/jobs/career-steps.ts): `server/src/jobs/career-steps.ts`
- [Posting intake](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/intake.ts): `server/src/career/intake.ts`
- [CV tailoring](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/tailor.ts): `server/src/career/tailor.ts`
- [Draft model](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/draft.ts): `server/src/career/draft.ts`
- [Fit and verification](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/ats.ts): `server/src/career/ats.ts`
- [Cover letter](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/career/letter.ts): `server/src/career/letter.ts`
- [Document rendering](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/jobs/career-render.ts): `server/src/jobs/career-render.ts`

### Email workflows

- [Email API routes](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/email.ts): `server/src/http/routes/email.ts`
- [Mail analysis and triage](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/triage.ts): `server/src/mail/triage.ts`
- [Gmail sync](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/sync.ts): `server/src/mail/sync.ts`
- [Gmail authorization](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/oauth.ts): `server/src/mail/oauth.ts`
- [Gmail client](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/mail/gmail.ts): `server/src/mail/gmail.ts`

### Local platform

- [HTTP application](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/app.ts): `server/src/app.ts`
- [Local SQLite database](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/db/index.ts): `server/src/db/index.ts`
- **Configured LLM provider**
- [LLM client and usage ledger](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/llm/client.ts): `server/src/llm/client.ts`
- [Personal knowledge vault](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/vault/writer.ts): `server/src/vault/writer.ts`
- [Dashboard and status](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/http/routes/dashboard.ts): `server/src/http/routes/dashboard.ts`
- [Approval workflow](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/approvals/apply.ts): `server/src/approvals/apply.ts`
- [Local email decider](https://github.com/amirwebd3v/agentic-os/blob/main/server/src/decider/client.ts): `server/src/decider/client.ts`

### Other components

- **Personal user**
- **Laya sidecar**

## Connections

- Personal user → Vue application: uses (evidence: `README.md`)
- Vue application → Career views: routes to
- Vue application → Email views: routes to
- Career views → Web API client: requests data (evidence: `web/src/views/ApplicationView.vue`)
- Email views → Web API client: requests data
- Web API client → HTTP application: calls API (evidence: `README.md`)
- HTTP application → Career API routes: registers routes (evidence: `server/src/main.ts`)
- HTTP application → Master CV routes: registers routes (evidence: `server/src/main.ts`)
- HTTP application → Email API routes: registers routes (evidence: `server/src/main.ts`)
- HTTP application → Dashboard and status: registers routes (evidence: `server/src/main.ts`)
- HTTP application → Approval workflow: registers routes
- Career API routes → Career step jobs: dispatches jobs (evidence: `server/src/http/routes/career.ts`)
- Career step jobs → Posting intake: extracts requirements (evidence: `server/src/jobs/career-steps.ts`)
- Career step jobs → CV tailoring: reads and saves drafts (evidence: `server/src/jobs/career-steps.ts`)
- Career step jobs → Fit and verification: checks fit (evidence: `server/src/jobs/career-steps.ts`)
- Career step jobs → Cover letter: writes letter (evidence: `server/src/jobs/career-steps.ts`)
- Career API routes → Document rendering: requests rendering (evidence: `server/src/http/routes/career.ts`)
- Document rendering → Personal knowledge vault: writes documents (evidence: `server/src/jobs/career-render.ts`)
- Posting intake → LLM client and usage ledger: extracts with (evidence: `server/src/career/intake.ts`)
- Fit and verification → LLM client and usage ledger: checks with (evidence: `server/src/career/ats.ts`)
- Cover letter → LLM client and usage ledger: generates with (evidence: `server/src/career/letter.ts`)
- LLM client and usage ledger → Configured LLM provider: sends prompts (evidence: `server/src/llm/client.ts`)
- LLM client and usage ledger → Local SQLite database: records usage (evidence: `server/src/llm/client.ts`)
- Master CV routes → Personal knowledge vault: manages CV files
- Email API routes → Mail analysis and triage: dispatches analysis
- Email API routes → Gmail sync: starts sync
- Gmail sync → Gmail client: uses client
- Gmail authorization → Gmail client: uses client (evidence: `server/src/mail/oauth.ts`)
- Mail analysis and triage → Local email decider: may consult
- Local email decider → Laya sidecar: requests decisions
- Dashboard and status → Local SQLite database: reads status
- Approval workflow → Local SQLite database: applies approvals
