# umair777/founderai architecture

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

- Interactive diagram: https://gitdiagram.com/umair777/founderai
- Repository: https://github.com/umair777/founderai

## Overview

Founder AI is an evidence-first assistant: a founder asks a question through the UI or an API/CLI entry point; the service plans which sources to query, fetches and normalizes context, detects updates, retrieves evidence, gates generation on evidence availability, validates citations, and returns an answer with evidence and trace data. The main orchestration and storage behavior is supported by sampled source. API and CLI are documented product interfaces but their implementations were not sampled, so their wiring is shown only at the service boundary.

Main entry points: [`founder_ai/service.py`](https://github.com/umair777/founderai/blob/main/founder_ai/service.py) (Assistant service), [`founder_ai/context_store.py`](https://github.com/umair777/founderai/blob/main/founder_ai/context_store.py) (Context store), [`founder_ai/connectors.py`](https://github.com/umair777/founderai/blob/main/founder_ai/connectors.py) (Gmail connector), [`founder_ai/llm.py`](https://github.com/umair777/founderai/blob/main/founder_ai/llm.py) (LLM providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_gradio["Gradio UI<br/>[app.py]"]
  node_api["FastAPI<br/>[api.py]"]
  node_cli["CLI<br/>[cli.py]"]
end

subgraph group_orchestration["Question orchestration"]
  node_service["Assistant service<br/>[service.py]"]
  node_planner["Query planner<br/>[planner.py]"]
  node_contracts["Context and trace models<br/>[models.py]"]
end

subgraph group_sources["Context sources"]
  node_gmail["Gmail connector<br/>[connectors.py]"]
  node_calendar["Calendar connector<br/>[connectors.py]"]
  node_linear["Linear connector<br/>[connectors.py]"]
end

subgraph group_evidence["Evidence and state"]
  node_store["Context store<br/>[context_store.py]"]
  node_sqlite[("SQLite database<br/>[founder_ai.db]")]
end

subgraph group_answers["Grounded answers"]
  node_generator["LLM providers<br/>[llm.py]"]
  node_validator["Citation validator<br/>[validation.py]"]
  node_response["Answer and trace<br/>[models.py]"]
end

node_founder(("Founder"))
node_google{{"Google services"}}
node_linear_service{{"Linear service"}}
node_embeddings{{"SentenceTransformers"}}
node_hosted_llm{{"OpenAI / OpenRouter"}}
node_tinyllama{{"TinyLlama"}}

node_founder -->|"asks via"| node_gradio
node_gradio -->|"calls ask"| node_service
node_api -->|"calls service"| node_service
node_cli -->|"calls service"| node_service
node_service -->|"plans query"| node_planner
node_planner -->|"returns plan"| node_service
node_service -->|"dispatches plan"| node_gmail
node_service -->|"dispatches plan"| node_calendar
node_service -->|"dispatches plan"| node_linear
node_gmail -->|"fetches mail"| node_google
node_calendar -->|"fetches events"| node_google
node_linear -.->|"fetches context"| node_linear_service
node_gmail -->|"returns items"| node_service
node_calendar -->|"returns items"| node_service
node_linear -->|"returns items"| node_service
node_service -->|"ingests items"| node_store
node_service -->|"searches evidence"| node_store
node_store -->|"reads and writes"| node_sqlite
node_store -.->|"encodes text"| node_embeddings
node_store -->|"returns evidence and updates"| node_service
node_service -->|"generates from evidence"| node_generator
node_generator -.->|"sends prompt"| node_hosted_llm
node_generator -.->|"runs local model"| node_tinyllama
node_service -->|"validates citations"| node_validator
node_service -->|"builds trace and response"| node_contracts
node_service -->|"returns result"| node_response
node_service -->|"returns answer and evidence"| node_gradio

click node_gradio "https://github.com/umair777/founderai/blob/main/app.py"
click node_api "https://github.com/umair777/founderai/blob/main/founder_ai/api.py"
click node_cli "https://github.com/umair777/founderai/blob/main/founder_ai/cli.py"
click node_service "https://github.com/umair777/founderai/blob/main/founder_ai/service.py"
click node_planner "https://github.com/umair777/founderai/blob/main/founder_ai/planner.py"
click node_contracts "https://github.com/umair777/founderai/blob/main/founder_ai/models.py"
click node_gmail "https://github.com/umair777/founderai/blob/main/founder_ai/connectors.py"
click node_calendar "https://github.com/umair777/founderai/blob/main/founder_ai/connectors.py"
click node_linear "https://github.com/umair777/founderai/blob/main/founder_ai/connectors.py"
click node_store "https://github.com/umair777/founderai/blob/main/founder_ai/context_store.py"
click node_sqlite "https://github.com/umair777/founderai/blob/main/founder_ai.db"
click node_generator "https://github.com/umair777/founderai/blob/main/founder_ai/llm.py"
click node_validator "https://github.com/umair777/founderai/blob/main/founder_ai/validation.py"
click node_response "https://github.com/umair777/founderai/blob/main/founder_ai/models.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_gradio,node_api,node_cli toneBlue
class node_service,node_planner,node_contracts toneAmber
class node_gmail,node_calendar,node_linear,node_hosted_llm toneMint
class node_store,node_sqlite toneRose
class node_generator,node_validator,node_response,node_founder,node_google,node_linear_service,node_embeddings,node_tinyllama toneIndigo
```

## Components

### User interfaces

- [Gradio UI](https://github.com/umair777/founderai/blob/main/app.py): `app.py`
- [FastAPI](https://github.com/umair777/founderai/blob/main/founder_ai/api.py): `founder_ai/api.py`
- [CLI](https://github.com/umair777/founderai/blob/main/founder_ai/cli.py): `founder_ai/cli.py`

### Question orchestration

- [Assistant service](https://github.com/umair777/founderai/blob/main/founder_ai/service.py): `founder_ai/service.py`
- [Query planner](https://github.com/umair777/founderai/blob/main/founder_ai/planner.py): `founder_ai/planner.py`
- [Context and trace models](https://github.com/umair777/founderai/blob/main/founder_ai/models.py): `founder_ai/models.py`

### Context sources

- [Gmail connector](https://github.com/umair777/founderai/blob/main/founder_ai/connectors.py): `founder_ai/connectors.py`
- [Calendar connector](https://github.com/umair777/founderai/blob/main/founder_ai/connectors.py): `founder_ai/connectors.py`
- [Linear connector](https://github.com/umair777/founderai/blob/main/founder_ai/connectors.py): `founder_ai/connectors.py`

### Evidence and state

- [Context store](https://github.com/umair777/founderai/blob/main/founder_ai/context_store.py): `founder_ai/context_store.py`
- [SQLite database](https://github.com/umair777/founderai/blob/main/founder_ai.db): `founder_ai.db`

### Grounded answers

- [LLM providers](https://github.com/umair777/founderai/blob/main/founder_ai/llm.py): `founder_ai/llm.py`
- [Citation validator](https://github.com/umair777/founderai/blob/main/founder_ai/validation.py): `founder_ai/validation.py`
- [Answer and trace](https://github.com/umair777/founderai/blob/main/founder_ai/models.py): `founder_ai/models.py`

### Other components

- **Founder**
- **Google services**
- **Linear service**
- **SentenceTransformers**
- **OpenAI / OpenRouter**
- **TinyLlama**

## Connections

- Founder → Gradio UI: asks via
- Gradio UI → Assistant service: calls ask
- FastAPI → Assistant service: calls service
- CLI → Assistant service: calls service
- Assistant service → Query planner: plans query
- Query planner → Assistant service: returns plan
- Assistant service → Gmail connector: dispatches plan
- Assistant service → Calendar connector: dispatches plan
- Assistant service → Linear connector: dispatches plan
- Gmail connector → Google services: fetches mail
- Calendar connector → Google services: fetches events
- Linear connector → Linear service: fetches context
- Gmail connector → Assistant service: returns items
- Calendar connector → Assistant service: returns items
- Linear connector → Assistant service: returns items
- Assistant service → Context store: ingests items
- Assistant service → Context store: searches evidence
- Context store → SQLite database: reads and writes
- Context store → SentenceTransformers: encodes text
- Context store → Assistant service: returns evidence and updates
- Assistant service → LLM providers: generates from evidence
- LLM providers → OpenAI / OpenRouter: sends prompt
- LLM providers → TinyLlama: runs local model
- Assistant service → Citation validator: validates citations
- Assistant service → Context and trace models: builds trace and response
- Assistant service → Answer and trace: returns result
- Assistant service → Gradio UI: returns answer and evidence