# sarma45/skillhub architecture

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

- Interactive diagram: https://gitdiagram.com/sarma45/skillhub
- Repository: https://github.com/sarma45/skillhub

## Overview

AI Engineering Cockpit guides a person from repository import and editable repository facts through task framing, versioned plan approval, isolated execution, evidence-backed review, and a gated pull-request draft. A durable worker orchestrates repository indexing, planning, runs, and security scans; policy and contracts bound the workflow. Separate capabilities cover approved project memory, context assembly, browser verification, model routing, skill extraction/catalog, and quality evaluation. The worker and selected routes are sampled; other capability links reflect README documentation, so uncertain internal call wiring is omitted.

Main entry points: [`apps/worker/src/main.ts`](https://github.com/sarma45/skillhub/blob/main/apps/worker/src/main.ts) (Job worker), [`apps/web/src/app/api/v1`](https://github.com/sarma45/skillhub/tree/main/apps/web/src/app/api/v1) (HTTP API), [`packages/db/src/index.ts`](https://github.com/sarma45/skillhub/blob/main/packages/db/src/index.ts) (Cockpit database), [`apps/web/src/server/app-layer.ts`](https://github.com/sarma45/skillhub/blob/main/apps/web/src/server/app-layer.ts) (Application layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace UI and API"]
  node_webui["Cockpit UI"]
  node_api["HTTP API"]
  node_app_layer["Application layer<br/>[app-layer.ts]"]
end

subgraph group_workflow["Engineering workflow"]
  node_worker["Job worker<br/>[main.ts]"]
  node_repo_parser["Repository mapping<br/>[index.ts]"]
  node_planning["Plan generation<br/>[index.ts]"]
  node_execution["Run execution<br/>[engine.ts]"]
  node_workspace_runtime["Isolated workspace<br/>[workspace.ts]"]
end

subgraph group_services["Capabilities and integrations"]
  node_context["Context assembly<br/>[index.ts]"]
  node_memory["Project memory<br/>[index.ts]"]
  node_browser["Browser verification<br/>[index.ts]"]
  node_routing["Model routing<br/>[index.ts]"]
  node_gateway["Model gateway<br/>[index.ts]"]
  node_evaluation["Quality evaluation<br/>[index.ts]"]
  node_security["Security scanning<br/>[index.ts]"]
  node_skill_extract["Skill extraction<br/>[index.ts]"]
  node_skill_registry["Skill catalog<br/>[index.ts]"]
end

subgraph group_foundation["Policy and persistence"]
  node_policy["Safety policy<br/>[index.ts]"]
  node_contracts["Domain contracts<br/>[index.ts]"]
  node_database[("Cockpit database<br/>[index.ts]")]
end

node_person(("Engineer"))
node_provider["Model providers"]
node_browser_target["Local browser target"]
node_safe_fixture["Safe-lab fixture<br/>[server.js]"]

node_person -->|"uses"| node_webui
node_webui -->|"requests"| node_api
node_api -->|"dispatches"| node_app_layer
node_app_layer -->|"reads/writes"| node_database
node_app_layer -->|"queues jobs"| node_worker
node_worker -->|"claims jobs"| node_database
node_worker -->|"builds map"| node_repo_parser
node_worker -->|"stores map"| node_database
node_worker -->|"assembles context"| node_context
node_worker -->|"generates plan"| node_planning
node_worker -->|"runs plan"| node_execution
node_execution -->|"uses workspace"| node_workspace_runtime
node_execution -->|"redacts receipts"| node_policy
node_worker -->|"stores run events"| node_database
node_worker -->|"records lessons"| node_memory
node_worker -->|"evaluates changes"| node_evaluation
node_worker -->|"runs scans"| node_security
node_security -->|"scans locally"| node_safe_fixture
node_api -->|"creates captures"| node_browser
node_browser -->|"verifies"| node_browser_target
node_api -->|"extracts skills"| node_skill_extract
node_skill_extract -->|"proposes skills"| node_skill_registry
node_api -->|"lists catalog"| node_skill_registry
node_worker -->|"creates tool gateway"| node_gateway
node_gateway -.->|"routes requests"| node_provider
node_routing -.->|"selects provider"| node_provider
node_context -->|"includes memories"| node_memory
node_api -->|"enforces boundaries"| node_policy
node_api -->|"validates payloads"| node_contracts

click node_webui "https://github.com/sarma45/skillhub/tree/main/apps/web/src/app"
click node_api "https://github.com/sarma45/skillhub/tree/main/apps/web/src/app/api/v1"
click node_app_layer "https://github.com/sarma45/skillhub/blob/main/apps/web/src/server/app-layer.ts"
click node_worker "https://github.com/sarma45/skillhub/blob/main/apps/worker/src/main.ts"
click node_repo_parser "https://github.com/sarma45/skillhub/blob/main/services/repo-parser/src/index.ts"
click node_planning "https://github.com/sarma45/skillhub/blob/main/services/planning-service/src/index.ts"
click node_execution "https://github.com/sarma45/skillhub/blob/main/services/execution-engine/src/engine.ts"
click node_workspace_runtime "https://github.com/sarma45/skillhub/blob/main/services/execution-engine/src/workspace.ts"
click node_context "https://github.com/sarma45/skillhub/blob/main/services/context-service/src/index.ts"
click node_memory "https://github.com/sarma45/skillhub/blob/main/services/memory-service/src/index.ts"
click node_browser "https://github.com/sarma45/skillhub/blob/main/services/browser-service/src/index.ts"
click node_routing "https://github.com/sarma45/skillhub/blob/main/services/routing-service/src/index.ts"
click node_gateway "https://github.com/sarma45/skillhub/blob/main/packages/model-gateway/src/index.ts"
click node_evaluation "https://github.com/sarma45/skillhub/blob/main/services/evaluation-service/src/index.ts"
click node_security "https://github.com/sarma45/skillhub/blob/main/services/security-service/src/index.ts"
click node_skill_extract "https://github.com/sarma45/skillhub/blob/main/services/extraction-service/src/index.ts"
click node_skill_registry "https://github.com/sarma45/skillhub/blob/main/services/skill-registry/src/index.ts"
click node_policy "https://github.com/sarma45/skillhub/blob/main/packages/policy/src/index.ts"
click node_contracts "https://github.com/sarma45/skillhub/blob/main/packages/contracts/src/index.ts"
click node_database "https://github.com/sarma45/skillhub/blob/main/packages/db/src/index.ts"
click node_safe_fixture "https://github.com/sarma45/skillhub/blob/main/security-fixtures/vulnerable-app/server.js"

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_webui,node_api,node_app_layer,node_browser_target toneBlue
class node_worker,node_repo_parser,node_planning,node_execution,node_workspace_runtime toneAmber
class node_context,node_memory,node_browser,node_routing,node_gateway,node_evaluation,node_security,node_skill_extract,node_skill_registry toneMint
class node_policy,node_contracts,node_database toneRose
class node_person,node_provider toneIndigo
class node_safe_fixture toneTeal
```

## Components

### Workspace UI and API

- [Cockpit UI](https://github.com/sarma45/skillhub/tree/main/apps/web/src/app): `apps/web/src/app`
- [HTTP API](https://github.com/sarma45/skillhub/tree/main/apps/web/src/app/api/v1): `apps/web/src/app/api/v1`
- [Application layer](https://github.com/sarma45/skillhub/blob/main/apps/web/src/server/app-layer.ts): `apps/web/src/server/app-layer.ts`

### Engineering workflow

- [Job worker](https://github.com/sarma45/skillhub/blob/main/apps/worker/src/main.ts): `apps/worker/src/main.ts`
- [Repository mapping](https://github.com/sarma45/skillhub/blob/main/services/repo-parser/src/index.ts): `services/repo-parser/src/index.ts`
- [Plan generation](https://github.com/sarma45/skillhub/blob/main/services/planning-service/src/index.ts): `services/planning-service/src/index.ts`
- [Run execution](https://github.com/sarma45/skillhub/blob/main/services/execution-engine/src/engine.ts): `services/execution-engine/src/engine.ts`
- [Isolated workspace](https://github.com/sarma45/skillhub/blob/main/services/execution-engine/src/workspace.ts): `services/execution-engine/src/workspace.ts`

### Capabilities and integrations

- [Context assembly](https://github.com/sarma45/skillhub/blob/main/services/context-service/src/index.ts): `services/context-service/src/index.ts`
- [Project memory](https://github.com/sarma45/skillhub/blob/main/services/memory-service/src/index.ts): `services/memory-service/src/index.ts`
- [Browser verification](https://github.com/sarma45/skillhub/blob/main/services/browser-service/src/index.ts): `services/browser-service/src/index.ts`
- [Model routing](https://github.com/sarma45/skillhub/blob/main/services/routing-service/src/index.ts): `services/routing-service/src/index.ts`
- [Model gateway](https://github.com/sarma45/skillhub/blob/main/packages/model-gateway/src/index.ts): `packages/model-gateway/src/index.ts`
- [Quality evaluation](https://github.com/sarma45/skillhub/blob/main/services/evaluation-service/src/index.ts): `services/evaluation-service/src/index.ts`
- [Security scanning](https://github.com/sarma45/skillhub/blob/main/services/security-service/src/index.ts): `services/security-service/src/index.ts`
- [Skill extraction](https://github.com/sarma45/skillhub/blob/main/services/extraction-service/src/index.ts): `services/extraction-service/src/index.ts`
- [Skill catalog](https://github.com/sarma45/skillhub/blob/main/services/skill-registry/src/index.ts): `services/skill-registry/src/index.ts`

### Policy and persistence

- [Safety policy](https://github.com/sarma45/skillhub/blob/main/packages/policy/src/index.ts): `packages/policy/src/index.ts`
- [Domain contracts](https://github.com/sarma45/skillhub/blob/main/packages/contracts/src/index.ts): `packages/contracts/src/index.ts`
- [Cockpit database](https://github.com/sarma45/skillhub/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`

### Other components

- **Engineer**
- **Model providers**
- **Local browser target**
- [Safe-lab fixture](https://github.com/sarma45/skillhub/blob/main/security-fixtures/vulnerable-app/server.js): `security-fixtures/vulnerable-app/server.js`

## Connections

- Engineer → Cockpit UI: uses
- Cockpit UI → HTTP API: requests
- HTTP API → Application layer: dispatches
- Application layer → Cockpit database: reads/writes
- Application layer → Job worker: queues jobs
- Job worker → Cockpit database: claims jobs
- Job worker → Repository mapping: builds map
- Job worker → Cockpit database: stores map
- Job worker → Context assembly: assembles context
- Job worker → Plan generation: generates plan
- Job worker → Run execution: runs plan
- Run execution → Isolated workspace: uses workspace
- Run execution → Safety policy: redacts receipts
- Job worker → Cockpit database: stores run events
- Job worker → Project memory: records lessons
- Job worker → Quality evaluation: evaluates changes
- Job worker → Security scanning: runs scans
- Security scanning → Safe-lab fixture: scans locally
- HTTP API → Browser verification: creates captures
- Browser verification → Local browser target: verifies
- HTTP API → Skill extraction: extracts skills
- Skill extraction → Skill catalog: proposes skills
- HTTP API → Skill catalog: lists catalog
- Job worker → Model gateway: creates tool gateway
- Model gateway → Model providers: routes requests
- Model routing → Model providers: selects provider
- Context assembly → Project memory: includes memories
- HTTP API → Safety policy: enforces boundaries
- HTTP API → Domain contracts: validates payloads