# williamkoller/chronos-ai architecture

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

- Interactive diagram: https://gitdiagram.com/williamkoller/chronos-ai
- Repository: https://github.com/williamkoller/chronos-ai

## Overview

##### Project Type and Purpose
- Chronos AI is a full-stack productivity assistant combining:
- A Streamlit dashboard (frontend)
- A FastAPI service (backend/API)
- A hybrid AI engine (dev-mode rules + LocalAI in production)
- A Notion integration and a lightweight local database
- Purpose: Automate and optimize personal task scheduling via intelligent algorithms and local LLM inference.

##### File Structure
- Top-level directories:
- api/ → FastAPI endpoints (main.py)
- dashboard/ → Streamlit UI (app.py)
- core/ → Business logic (models.py, scheduler.py)
- integrations/ → External service clients (Notion, AI dev client)
- learning/ → Feedback-based ML components (pattern_analyzer, feedback_processor)
- localai/ → LocalAI model and config files (production LLM)
- Config and orchestration:
- docker-compose.yml, Dockerfile.api, Dockerfile.dashboard for containerization
- Makefile for automation (setup, up, down, logs, tests)
- .env.example for secrets and environment variables
- chronos_knowledge.db for local SQLite storage

##### README for Additional Insights
- Architecture section already shows three main blocks: Dashboard ↔ API ↔ Hybrid AI Engine
- Database is PostgreSQL in production (SQLite local for dev)
- LocalAI runs on port 8080; API on 8000; Dashboard on 8501
- Hybrid AI Engine toggles between rule-based dev mode and LocalAI container based on AI_DEV_MODE
- Integrations: Notion API for task syncing

##### Elements
- Labels: component names, ports, key directories
- UI → API → AI Engine and Database
- API ↔ Notion API
- learning modules ← API/core → scheduler
- Rectangles for services (API, Dashboard, LocalAI)
- Clouds for external services (Notion API)

## Diagram (Mermaid)

```mermaid
graph TB
  %% Frontend Layer
  subgraph "Frontend"
    direction TB
    Dashboard["Streamlit Dashboard<br/>(Port 8501)"]:::frontend
    ConfigToml[".streamlit/config.toml"]:::infra
  end

  %% Backend Layer
  subgraph "Backend"
    direction TB
    API["FastAPI Service<br/>(Port 8000)"]:::backend
    CoreScheduler["Scheduler Logic<br/>(core/scheduler.py)"]:::backend
    CoreModels["Data Models<br/>(core/models.py)"]:::backend
    subgraph "Integrations"
      direction TB
      AIClient["Rule-Based Engine (Dev Mode)"]:::ai
      NotionClient["Notion Client"]:::external
      NotionDiag["Notion Diagnostics"]:::external
      SetupNotion["Notion DB Setup"]:::infra
    end
  end

  %% AI Engine Layer
  subgraph "AI Engine"
    direction TB
    subgraph "LocalAI Inference"
      direction TB
      LocalAISvc["LocalAI Container<br/>(Port 8080)"]:::ai
      LocalAIConfig["gpt-3.5-turbo.yaml"]:::ai
      LocalAIModel["gpt-3.5-turbo Model"]:::ai
    end
  end

  %% Database Layer
  subgraph "Data Persistence"
    direction TB
    DB["SQLite / PostgreSQL"]:::db
    EnvFile[".env.example"]:::infra
  end

  %% Learning & Feedback Loop
  subgraph "Learning"
    direction TB
    PatternAnalyzer["Pattern Analyzer"]:::learning
    FeedbackProcessor["Feedback Processor"]:::learning
  end

  %% Container Orchestration
  subgraph "Orchestration & Automation"
    direction TB
    DockerCompose["docker-compose.yml"]:::infra
    Makefile["Makefile"]:::infra
    CheckProps["Property Checker"]:::infra
    DockerfileAPI["Dockerfile.api"]:::infra
    DockerfileDash["Dockerfile.dashboard"]:::infra
  end

  %% External Services
  NotionAPI["Notion API"]:::external

  %% Connections
  Dashboard -->|"HTTP 8501→8000"| API
  API -->|"invoke rules"| AIClient
  API -->|"HTTP 8000→8080"| LocalAISvc
  AIClient -.->|fallback toggle| LocalAISvc
  API -->|"read/write"| DB
  API -->|"sync tasks"| NotionAPI
  API -->|"notify"| NotionClient
  CoreScheduler -->|"sends patterns"| PatternAnalyzer
  PatternAnalyzer --> FeedbackProcessor
  FeedbackProcessor -->|"update logic"| CoreScheduler

  %% Orchestration links
  DockerCompose --> Dashboard
  DockerCompose --> API
  DockerCompose --> LocalAISvc
  Makefile --> DockerCompose
  DockerCompose --> DockerfileAPI
  DockerCompose --> DockerfileDash
  Makefile --> CheckProps

  %% Click Events
  click Dashboard "https://github.com/williamkoller/chronos-ai/blob/main/dashboard/app.py"
  click ConfigToml "https://github.com/williamkoller/chronos-ai/blob/main/.streamlit/config.toml"
  click API "https://github.com/williamkoller/chronos-ai/blob/main/api/main.py"
  click DockerfileAPI "https://github.com/williamkoller/chronos-ai/blob/main/Dockerfile.api"
  click CoreScheduler "https://github.com/williamkoller/chronos-ai/blob/main/core/scheduler.py"
  click CoreModels "https://github.com/williamkoller/chronos-ai/blob/main/core/models.py"
  click AIClient "https://github.com/williamkoller/chronos-ai/blob/main/integrations/ai_client.py"
  click NotionClient "https://github.com/williamkoller/chronos-ai/blob/main/integrations/notion_client.py"
  click NotionDiag "https://github.com/williamkoller/chronos-ai/blob/main/integrations/notion_diagnostic.py"
  click SetupNotion "https://github.com/williamkoller/chronos-ai/blob/main/scripts/setup_notion_database.py"
  click LocalAIConfig "https://github.com/williamkoller/chronos-ai/blob/main/localai/config/gpt-3.5-turbo.yaml"
  click LocalAIModel "https://github.com/williamkoller/chronos-ai/blob/main/localai/models/gpt-3.5-turbo"
  click DB "https://github.com/williamkoller/chronos-ai/blob/main/chronos_knowledge.db"
  click EnvFile "https://github.com/williamkoller/chronos-ai/blob/main/.env.example"
  click DockerCompose "https://github.com/williamkoller/chronos-ai/blob/main/docker-compose.yml"
  click Makefile "https://github.com/williamkoller/chronos-ai/tree/main/Makefile"
  click CheckProps "https://github.com/williamkoller/chronos-ai/blob/main/scripts/check_properties.py"
  click DockerfileDash "https://github.com/williamkoller/chronos-ai/blob/main/Dockerfile.dashboard"

  %% Styles
  classDef frontend fill:#D6EAF8,stroke:#2980B9,color:#154360;
  classDef backend fill:#D5F5E3,stroke:#27AE60,color:#145A32;
  classDef ai fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
  classDef db fill:#FCF3A6,stroke:#F39C12,color:#7E5109;
  classDef external fill:#E5E8E8,stroke:#566573,color:#2C3E50;
  classDef infra fill:#F2F3F4,stroke:#AAB7B8,color:#424949;
  classDef learning fill:#FADBD8,stroke:#EC7063,color:#641E16;
```
