# pranithvelar/friday_mark2 architecture

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

- Interactive diagram: https://gitdiagram.com/pranithvelar/friday_mark2
- Repository: https://github.com/pranithvelar/friday_mark2

## Overview

Friday is a hybrid cloud/local personal assistant. A user enters through a terminal or messaging interface; the central router classifies the request and dispatches simple, tool-oriented, or multi-step work. Complex work is planned, optionally approved, then executed asynchronously through registered tools. Supporting branches provide LLM fallback, persistent-memory learning, live awareness, search, and calendar capabilities. Several of these capabilities are documented in the README but their implementations were not sampled, so those relationships are shown only where documented.

Main entry points: [`friday/router/smart_router.py`](https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/smart_router.py) (Smart router), [`friday/router/handlers/complex_handler.py`](https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/handlers/complex_handler.py) (Complex planner), [`friday/agents/friday/agent.py`](https://github.com/pranithvelar/friday_mark2/blob/main/friday/agents/friday/agent.py) (Friday agent), [`friday/execution/engine.py`](https://github.com/pranithvelar/friday_mark2/blob/main/friday/execution/engine.py) (Execution engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces and routing"]
  node_terminal["Terminal chat<br/>[chat.py]"]
  node_messaging["Messaging adapters"]
  node_router["Smart router<br/>[smart_router.py]"]
  node_classifier["Intent classifier"]
  node_simple["Simple handler<br/>[simple_handler.py]"]
  node_medium["Medium handler<br/>[medium_handler.py]"]
end

subgraph group_agents["Assistant and agents"]
  node_friday["Friday agent<br/>[agent.py]"]
  node_reflection["Self-critique<br/>[reflection.py]"]
end

subgraph group_execution["Planning and execution"]
  node_planner["Complex planner<br/>[complex_handler.py]"]
  node_engine["Execution engine<br/>[engine.py]"]
  node_state["Execution state<br/>[state_manager.py]"]
  node_tools["Tool registry<br/>[registry.py]"]
end

subgraph group_memory["Memory and awareness"]
  node_memory_learning["Background learning"]
  node_decay["Memory decay<br/>[memory_decay.py]"]
  node_context["Live context<br/>[live_context.py]"]
  node_search[("Full-text search<br/>[fts_search.py]")]
end

subgraph group_services["Models and capabilities"]
  node_llm["Slotted LLM provider"]
  node_calendar["Calendar and events"]
  node_rag["RAG agent<br/>[agent.py]"]
  node_redis[("Redis cache<br/>[redis_client.py]")]
end

node_user(("User"))

node_user -->|"sends request"| node_terminal
node_user -->|"sends message"| node_messaging
node_terminal -->|"routes query"| node_router
node_router -->|"classifies query"| node_classifier
node_router -->|"dispatches simple"| node_simple
node_router -->|"dispatches medium"| node_medium
node_router -->|"dispatches complex"| node_planner
node_simple -.->|"uses agent"| node_friday
node_medium -.->|"calls tools"| node_tools
node_friday -->|"generates responses"| node_llm
node_planner -->|"generates plan"| node_llm
node_planner -->|"searches context"| node_search
node_planner -->|"starts execution"| node_engine
node_engine -->|"updates state"| node_state
node_engine -->|"dispatches steps"| node_tools
node_router -->|"starts memory pipeline"| node_memory_learning
node_router -.->|"uses live context"| node_context
node_memory_learning -.->|"maintains memory"| node_decay
node_friday -.->|"learns from corrections"| node_reflection
node_context -.->|"reads execution status"| node_state
node_rag -->|"caches embeddings"| node_redis
node_user -.->|"requests calendar actions"| node_calendar

click node_terminal "https://github.com/pranithvelar/friday_mark2/blob/main/friday/interfaces/terminal/chat.py"
click node_messaging "https://github.com/pranithvelar/friday_mark2/tree/main/friday/interfaces/messaging"
click node_router "https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/smart_router.py"
click node_classifier "https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/intent_classifier.py"
click node_simple "https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/handlers/simple_handler.py"
click node_medium "https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/handlers/medium_handler.py"
click node_friday "https://github.com/pranithvelar/friday_mark2/blob/main/friday/agents/friday/agent.py"
click node_reflection "https://github.com/pranithvelar/friday_mark2/blob/main/friday/reasoning/reflection.py"
click node_planner "https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/handlers/complex_handler.py"
click node_engine "https://github.com/pranithvelar/friday_mark2/blob/main/friday/execution/engine.py"
click node_state "https://github.com/pranithvelar/friday_mark2/blob/main/friday/execution/state_manager.py"
click node_tools "https://github.com/pranithvelar/friday_mark2/blob/main/friday/tools/registry.py"
click node_memory_learning "https://github.com/pranithvelar/friday_mark2/blob/main/friday/background/knowledge_extractor.py"
click node_decay "https://github.com/pranithvelar/friday_mark2/blob/main/friday/background/memory_decay.py"
click node_context "https://github.com/pranithvelar/friday_mark2/blob/main/friday/awareness/live_context.py"
click node_search "https://github.com/pranithvelar/friday_mark2/blob/main/friday/search/fts_search.py"
click node_llm "https://github.com/pranithvelar/friday_mark2/blob/main/friday/llm/slotted_provider.py"
click node_calendar "https://github.com/pranithvelar/friday_mark2/tree/main/friday/tools/calendar"
click node_rag "https://github.com/pranithvelar/friday_mark2/blob/main/friday/agents/specialized/rag/agent.py"
click node_redis "https://github.com/pranithvelar/friday_mark2/blob/main/friday/cache/redis_client.py"

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_terminal,node_messaging,node_router,node_classifier,node_simple,node_medium,node_user toneBlue
class node_friday,node_reflection toneAmber
class node_planner,node_engine,node_state,node_tools toneMint
class node_memory_learning,node_decay,node_context,node_search toneRose
class node_llm,node_calendar,node_rag,node_redis toneIndigo
```

## Components

### User interfaces and routing

- [Terminal chat](https://github.com/pranithvelar/friday_mark2/blob/main/friday/interfaces/terminal/chat.py): `friday/interfaces/terminal/chat.py`
- [Messaging adapters](https://github.com/pranithvelar/friday_mark2/tree/main/friday/interfaces/messaging): `friday/interfaces/messaging`
- [Smart router](https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/smart_router.py): `friday/router/smart_router.py`
- [Intent classifier](https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/intent_classifier.py): `friday/router/intent_classifier.py`
- [Simple handler](https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/handlers/simple_handler.py): `friday/router/handlers/simple_handler.py`
- [Medium handler](https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/handlers/medium_handler.py): `friday/router/handlers/medium_handler.py`

### Assistant and agents

- [Friday agent](https://github.com/pranithvelar/friday_mark2/blob/main/friday/agents/friday/agent.py): `friday/agents/friday/agent.py`
- [Self-critique](https://github.com/pranithvelar/friday_mark2/blob/main/friday/reasoning/reflection.py): `friday/reasoning/reflection.py`

### Planning and execution

- [Complex planner](https://github.com/pranithvelar/friday_mark2/blob/main/friday/router/handlers/complex_handler.py): `friday/router/handlers/complex_handler.py`
- [Execution engine](https://github.com/pranithvelar/friday_mark2/blob/main/friday/execution/engine.py): `friday/execution/engine.py`
- [Execution state](https://github.com/pranithvelar/friday_mark2/blob/main/friday/execution/state_manager.py): `friday/execution/state_manager.py`
- [Tool registry](https://github.com/pranithvelar/friday_mark2/blob/main/friday/tools/registry.py): `friday/tools/registry.py`

### Memory and awareness

- [Background learning](https://github.com/pranithvelar/friday_mark2/blob/main/friday/background/knowledge_extractor.py): `friday/background/knowledge_extractor.py`
- [Memory decay](https://github.com/pranithvelar/friday_mark2/blob/main/friday/background/memory_decay.py): `friday/background/memory_decay.py`
- [Live context](https://github.com/pranithvelar/friday_mark2/blob/main/friday/awareness/live_context.py): `friday/awareness/live_context.py`
- [Full-text search](https://github.com/pranithvelar/friday_mark2/blob/main/friday/search/fts_search.py): `friday/search/fts_search.py`

### Models and capabilities

- [Slotted LLM provider](https://github.com/pranithvelar/friday_mark2/blob/main/friday/llm/slotted_provider.py): `friday/llm/slotted_provider.py`
- [Calendar and events](https://github.com/pranithvelar/friday_mark2/tree/main/friday/tools/calendar): `friday/tools/calendar`
- [RAG agent](https://github.com/pranithvelar/friday_mark2/blob/main/friday/agents/specialized/rag/agent.py): `friday/agents/specialized/rag/agent.py`
- [Redis cache](https://github.com/pranithvelar/friday_mark2/blob/main/friday/cache/redis_client.py): `friday/cache/redis_client.py`

### Other components

- **User**

## Connections

- User → Terminal chat: sends request
- User → Messaging adapters: sends message
- Terminal chat → Smart router: routes query (evidence: `friday/interfaces/terminal/chat.py`)
- Smart router → Intent classifier: classifies query (evidence: `friday/router/smart_router.py`)
- Smart router → Simple handler: dispatches simple (evidence: `friday/router/smart_router.py`)
- Smart router → Medium handler: dispatches medium (evidence: `friday/router/smart_router.py`)
- Smart router → Complex planner: dispatches complex (evidence: `friday/router/smart_router.py`)
- Simple handler → Friday agent: uses agent
- Medium handler → Tool registry: calls tools
- Friday agent → Slotted LLM provider: generates responses (evidence: `friday/agents/friday/agent.py`)
- Complex planner → Slotted LLM provider: generates plan (evidence: `friday/router/handlers/complex_handler.py`)
- Complex planner → Full-text search: searches context (evidence: `friday/router/handlers/complex_handler.py`)
- Complex planner → Execution engine: starts execution (evidence: `friday/router/handlers/complex_handler.py`)
- Execution engine → Execution state: updates state (evidence: `friday/execution/engine.py`)
- Execution engine → Tool registry: dispatches steps (evidence: `friday/execution/engine.py`)
- Smart router → Background learning: starts memory pipeline (evidence: `friday/router/smart_router.py`)
- Smart router → Live context: uses live context
- Background learning → Memory decay: maintains memory
- Friday agent → Self-critique: learns from corrections
- Live context → Execution state: reads execution status
- RAG agent → Redis cache: caches embeddings
- User → Calendar and events: requests calendar actions