# jibankumar-cloud/faber architecture

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

- Interactive diagram: https://gitdiagram.com/jibankumar-cloud/faber
- Repository: https://github.com/jibankumar-cloud/faber

## Overview

Faber is a terminal-based AI coding assistant. The principal workflow is: a developer configures a model, submits a task, the agent streams model responses and dispatches tools, and approved edits or shell commands change the workspace; checkpoints support undo. Its code graph, persistent memory, session history, and usage ledger support that loop. The graph follows the supplied excerpts, SOURCE INDEX references, and README; unsampled implementation details and their unverified connections are not inferred.

Main entry points: [`src/agent.ts`](https://github.com/jibankumar-cloud/faber/blob/main/src/agent.ts) (Streaming agent loop), [`src/llm.ts`](https://github.com/jibankumar-cloud/faber/blob/main/src/llm.ts) (Model API client), [`src/index.ts`](https://github.com/jibankumar-cloud/faber/blob/main/src/index.ts) (Terminal REPL), [`src/config.ts`](https://github.com/jibankumar-cloud/faber/blob/main/src/config.ts) (Runtime configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and setup"]
  node_cli["Terminal REPL<br/>[index.ts]"]
  node_onboarding["Guided setup<br/>[onboard.ts]"]
  node_configuration["Runtime configuration<br/>[config.ts]"]
  node_settings["Profile settings<br/>[settings.ts]"]
end

subgraph group_agent["Agent workflow"]
  node_agentloop["Streaming agent loop<br/>[agent.ts]"]
end

subgraph group_state["Project state"]
  node_indexer[("Code graph index<br/>[indexer.ts]")]
  node_longmemory[("Long-term memory<br/>[longTerm.ts]")]
  node_shortmemory["Conversation context<br/>[shortTerm.ts]"]
  node_sessions[("Session history<br/>[sessions.ts]")]
  node_usage[("Usage ledger<br/>[usage.ts]")]
end

subgraph group_providers["Model providers"]
  node_routes["Provider routes<br/>[routes.ts]"]
  node_credentials["Credential resolution<br/>[credentials.ts]"]
  node_modelclient["Model API client<br/>[llm.ts]"]
  node_awsauth["AWS request signing<br/>[sigv4.ts]"]
  node_modelcatalog["Model catalog<br/>[models.ts]"]
  node_pricing["Model pricing<br/>[pricing.ts]"]
end

subgraph group_safety["Safe execution"]
  node_toolregistry["Tool dispatch<br/>[registry.ts]"]
  node_filesystem["Workspace file tools<br/>[fs.ts]"]
  node_shell["Shell execution<br/>[shell.ts]"]
  node_checkpoints["Change checkpoints<br/>[checkpoints.ts]"]
  node_git["Task git commits<br/>[git.ts]"]
end

node_developer(("Developer"))
node_workspace["Project workspace"]
node_provider(("Model provider"))

node_developer -->|"submits task"| node_cli
node_cli -->|"starts setup"| node_onboarding
node_cli -->|"loads config"| node_configuration
node_configuration -->|"loads profiles"| node_settings
node_configuration -->|"selects route"| node_routes
node_configuration -->|"resolves keys"| node_credentials
node_onboarding -->|"lists providers"| node_routes
node_cli -->|"runs tasks"| node_agentloop
node_agentloop -->|"requests responses"| node_modelclient
node_agentloop -->|"dispatches tools"| node_toolregistry
node_agentloop -->|"creates checkpoints"| node_checkpoints
node_agentloop -->|"uses memory"| node_longmemory
node_agentloop -->|"uses context"| node_shortmemory
node_agentloop -->|"persists sessions"| node_sessions
node_agentloop -->|"queries code graph"| node_indexer
node_agentloop -->|"records usage"| node_usage
node_agentloop -->|"commits task"| node_git
node_toolregistry -->|"dispatches file tools"| node_filesystem
node_toolregistry -->|"dispatches commands"| node_shell
node_filesystem -->|"reads and edits"| node_workspace
node_shell -->|"runs commands"| node_workspace
node_filesystem -->|"records changes"| node_checkpoints
node_modelclient -->|"streams requests"| node_provider
node_modelclient -->|"signs AWS requests"| node_awsauth
node_modelclient -->|"uses route config"| node_routes
node_modelclient -->|"uses model metadata"| node_modelcatalog
node_modelclient -->|"uses pricing data"| node_pricing
node_usage -->|"costs tokens"| node_pricing
node_developer -->|"approves edits"| node_filesystem
node_developer -->|"approves commands"| node_shell
node_developer -->|"undoes tasks"| node_cli

click node_cli "https://github.com/jibankumar-cloud/faber/blob/main/src/index.ts"
click node_onboarding "https://github.com/jibankumar-cloud/faber/blob/main/src/onboard.ts"
click node_configuration "https://github.com/jibankumar-cloud/faber/blob/main/src/config.ts"
click node_routes "https://github.com/jibankumar-cloud/faber/blob/main/src/routes.ts"
click node_settings "https://github.com/jibankumar-cloud/faber/blob/main/src/settings.ts"
click node_credentials "https://github.com/jibankumar-cloud/faber/blob/main/src/credentials.ts"
click node_agentloop "https://github.com/jibankumar-cloud/faber/blob/main/src/agent.ts"
click node_modelclient "https://github.com/jibankumar-cloud/faber/blob/main/src/llm.ts"
click node_awsauth "https://github.com/jibankumar-cloud/faber/blob/main/src/sigv4.ts"
click node_modelcatalog "https://github.com/jibankumar-cloud/faber/blob/main/src/models.ts"
click node_pricing "https://github.com/jibankumar-cloud/faber/blob/main/src/pricing.ts"
click node_toolregistry "https://github.com/jibankumar-cloud/faber/blob/main/src/tools/registry.ts"
click node_filesystem "https://github.com/jibankumar-cloud/faber/blob/main/src/tools/fs.ts"
click node_shell "https://github.com/jibankumar-cloud/faber/blob/main/src/tools/shell.ts"
click node_checkpoints "https://github.com/jibankumar-cloud/faber/blob/main/src/checkpoints.ts"
click node_git "https://github.com/jibankumar-cloud/faber/blob/main/src/git.ts"
click node_indexer "https://github.com/jibankumar-cloud/faber/blob/main/src/indexer.ts"
click node_longmemory "https://github.com/jibankumar-cloud/faber/blob/main/src/memory/longTerm.ts"
click node_shortmemory "https://github.com/jibankumar-cloud/faber/blob/main/src/memory/shortTerm.ts"
click node_sessions "https://github.com/jibankumar-cloud/faber/blob/main/src/memory/sessions.ts"
click node_usage "https://github.com/jibankumar-cloud/faber/blob/main/src/usage.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_cli,node_onboarding,node_configuration,node_settings toneBlue
class node_agentloop toneAmber
class node_indexer,node_longmemory,node_shortmemory,node_sessions,node_usage toneMint
class node_routes,node_credentials,node_modelclient,node_awsauth,node_modelcatalog,node_pricing toneRose
class node_toolregistry,node_filesystem,node_shell,node_checkpoints,node_git,node_developer,node_workspace,node_provider toneIndigo
```

## Components

### CLI and setup

- [Terminal REPL](https://github.com/jibankumar-cloud/faber/blob/main/src/index.ts): `src/index.ts`
- [Guided setup](https://github.com/jibankumar-cloud/faber/blob/main/src/onboard.ts): `src/onboard.ts`
- [Runtime configuration](https://github.com/jibankumar-cloud/faber/blob/main/src/config.ts): `src/config.ts`
- [Profile settings](https://github.com/jibankumar-cloud/faber/blob/main/src/settings.ts): `src/settings.ts`

### Agent workflow

- [Streaming agent loop](https://github.com/jibankumar-cloud/faber/blob/main/src/agent.ts): `src/agent.ts`

### Project state

- [Code graph index](https://github.com/jibankumar-cloud/faber/blob/main/src/indexer.ts): `src/indexer.ts`
- [Long-term memory](https://github.com/jibankumar-cloud/faber/blob/main/src/memory/longTerm.ts): `src/memory/longTerm.ts`
- [Conversation context](https://github.com/jibankumar-cloud/faber/blob/main/src/memory/shortTerm.ts): `src/memory/shortTerm.ts`
- [Session history](https://github.com/jibankumar-cloud/faber/blob/main/src/memory/sessions.ts): `src/memory/sessions.ts`
- [Usage ledger](https://github.com/jibankumar-cloud/faber/blob/main/src/usage.ts): `src/usage.ts`

### Model providers

- [Provider routes](https://github.com/jibankumar-cloud/faber/blob/main/src/routes.ts): `src/routes.ts`
- [Credential resolution](https://github.com/jibankumar-cloud/faber/blob/main/src/credentials.ts): `src/credentials.ts`
- [Model API client](https://github.com/jibankumar-cloud/faber/blob/main/src/llm.ts): `src/llm.ts`
- [AWS request signing](https://github.com/jibankumar-cloud/faber/blob/main/src/sigv4.ts): `src/sigv4.ts`
- [Model catalog](https://github.com/jibankumar-cloud/faber/blob/main/src/models.ts): `src/models.ts`
- [Model pricing](https://github.com/jibankumar-cloud/faber/blob/main/src/pricing.ts): `src/pricing.ts`

### Safe execution

- [Tool dispatch](https://github.com/jibankumar-cloud/faber/blob/main/src/tools/registry.ts): `src/tools/registry.ts`
- [Workspace file tools](https://github.com/jibankumar-cloud/faber/blob/main/src/tools/fs.ts): `src/tools/fs.ts`
- [Shell execution](https://github.com/jibankumar-cloud/faber/blob/main/src/tools/shell.ts): `src/tools/shell.ts`
- [Change checkpoints](https://github.com/jibankumar-cloud/faber/blob/main/src/checkpoints.ts): `src/checkpoints.ts`
- [Task git commits](https://github.com/jibankumar-cloud/faber/blob/main/src/git.ts): `src/git.ts`

### Other components

- **Developer**
- **Project workspace**
- **Model provider**

## Connections

- Developer → Terminal REPL: submits task (evidence: `README.md`)
- Terminal REPL → Guided setup: starts setup (evidence: `src/index.ts`)
- Terminal REPL → Runtime configuration: loads config (evidence: `src/index.ts`)
- Runtime configuration → Profile settings: loads profiles (evidence: `src/config.ts`)
- Runtime configuration → Provider routes: selects route (evidence: `src/config.ts`)
- Runtime configuration → Credential resolution: resolves keys (evidence: `src/config.ts`)
- Guided setup → Provider routes: lists providers (evidence: `src/onboard.ts`)
- Terminal REPL → Streaming agent loop: runs tasks (evidence: `src/index.ts`)
- Streaming agent loop → Model API client: requests responses (evidence: `src/agent.ts`)
- Streaming agent loop → Tool dispatch: dispatches tools (evidence: `src/agent.ts`)
- Streaming agent loop → Change checkpoints: creates checkpoints (evidence: `src/agent.ts`)
- Streaming agent loop → Long-term memory: uses memory (evidence: `src/agent.ts`)
- Streaming agent loop → Conversation context: uses context (evidence: `src/agent.ts`)
- Streaming agent loop → Session history: persists sessions (evidence: `src/agent.ts`)
- Streaming agent loop → Code graph index: queries code graph (evidence: `src/agent.ts`)
- Streaming agent loop → Usage ledger: records usage (evidence: `src/agent.ts`)
- Streaming agent loop → Task git commits: commits task (evidence: `src/agent.ts`)
- Tool dispatch → Workspace file tools: dispatches file tools (evidence: `src/tools/registry.ts`)
- Tool dispatch → Shell execution: dispatches commands (evidence: `src/tools/registry.ts`)
- Workspace file tools → Project workspace: reads and edits (evidence: `src/tools/fs.ts`)
- Shell execution → Project workspace: runs commands (evidence: `README.md`)
- Workspace file tools → Change checkpoints: records changes (evidence: `src/tools/fs.ts`)
- Model API client → Model provider: streams requests (evidence: `src/llm.ts`)
- Model API client → AWS request signing: signs AWS requests (evidence: `src/llm.ts`)
- Model API client → Provider routes: uses route config (evidence: `src/llm.ts`)
- Model API client → Model catalog: uses model metadata (evidence: `src/llm.ts`)
- Model API client → Model pricing: uses pricing data (evidence: `src/llm.ts`)
- Usage ledger → Model pricing: costs tokens (evidence: `src/usage.ts`)
- Developer → Workspace file tools: approves edits (evidence: `README.md`)
- Developer → Shell execution: approves commands (evidence: `README.md`)
- Developer → Terminal REPL: undoes tasks (evidence: `README.md`)
