# sfkunal/chronos architecture

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

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

## Overview

##### Main Components
- Frontend Client: This corresponds to the "chronos-frontend" directory. It consists of various pages (e.g., dashboards, specific user views like “lee” and “neha”), reusable components (e.g., ChatInterface, WeeklyCalendar, EventCard), utility hooks, and shared UI libraries. Highlight the integration with Google Calendar via API calls.
- Backend Server: Represent the "chronos-backend" directory. Key files such as app.py, groq_engine.py, and search_engine.py signal that the backend is responsible for:
- Handling incoming HTTP requests (from frontend calls or webhooks).
- Running natural language parsing and processing using the Groq LLM.
- Managing intelligent agents like the Intent Agent, Availability Agent, Preferences Agent, etc.
- Interfacing with external services such as Google Calendar/People APIs, ChromaDB for vector search, and Sentence Transformers.
- External Services & APIs: Include items like Google Calendar API, ChromaDB, Groq’s LLM, and any OAuth or user authentication services (OAuth 2.0).
- Data Flow Components: Include databases or storage where calendar events and preferences might be persisted. Although not explicitly visible in the file tree, they are implied by the features described in the README.

##### Out the Relationships and Data Flows
- Flow the input to the Intent Classification module (a component of backend agents) that uses Groq’s LLaMA 3.3 70B model for classifying commands into actions like create, delete, or edit.
- Integration points where the backend communicates with external services such as Google Calendar for event operations and ChromaDB for semantic search.
- Finally, illustrate how outcomes (updates or responses) propagate back to the Frontend for real-time updates (including detailed calendar views and smart chat-based interactions).

##### Architectural Patterns and Technologies
- Use an MVC-like separation for the backend: Controllers to handle requests in app.py, service modules (like groq_engine.py and search_engine.py) for business logic, and models (implied or abstracted) for event data.
- Micro-frontend structure if applicable; note that the frontend uses Next.js 13+ with an app directory pattern, organizing pages and components in a modular way.
- That the system leverages intelligent agents and a natural language processing pipeline, which is central to the project’s design.
- APIs and third-party integrations, especially for authentication via OAuth 2.0 and real-time event streaming.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    U["User"]:::external

    %% Frontend Layer
    subgraph "Next.js Frontend"
        F1["Dashboard Page"]:::frontend
        F2["Lee Page"]:::frontend
        F3["Neha Page"]:::frontend
        F4["Reusable UI Components"]:::frontend
        F5["Shared UI & Utilities"]:::frontend
    end

    %% Backend Layer
    subgraph "Flask Backend"
        B1["HTTP Controller (app.py)"]:::backend
        B2["NLP & Agent Orchestration (groq_engine.py)"]:::backend
        B3["Search Logic (search_engine.py)"]:::backend
        subgraph "Backend Agents"
            A1["Intent Agent"]:::backend
            A2["Availability Agent"]:::backend
            A3["Preferences Agent"]:::backend
            A4["Search Agent"]:::backend
            A5["Mutability Agent"]:::backend
            A6["Scheduling Agent"]:::backend
        end
    end

    %% External Services & APIs
    subgraph "External Services & APIs"
        EX1["Google Calendar API"]:::external
        EX2["OAuth2 Service"]:::external
        EX3["ChromaDB"]:::external
        EX4["Sentence Transformers"]:::external
        EX5["Groq's LLM"]:::external
    end

    %% Data Flow
    U -->|"NaturalLanguageInput"| F1
    U -->|"NaturalLanguageInput"| F2
    U -->|"NaturalLanguageInput"| F3

    F1 -->|"API_Call"| B1
    F2 -->|"API_Call"| B1
    F3 -->|"API_Call"| B1

    F4 -->|"UI_Interaction"| F1
    F4 -->|"UI_Interaction"| F2
    F4 -->|"UI_Interaction"| F3
    F5 -->|"Utility_Calls"| F1
    F5 -->|"Utility_Calls"| F2
    F5 -->|"Utility_Calls"| F3

    B1 -->|"Route_Request"| B2
    B1 -->|"Route_Request"| B3

    B2 -->|"Invoke_Agents"| A1
    B2 -->|"Invoke_Agents"| A2
    B2 -->|"Invoke_Agents"| A3
    B2 -->|"Invoke_Agents"| A4
    B2 -->|"Invoke_Agents"| A5
    B2 -->|"Invoke_Agents"| A6
    B2 -->|"Call_LLM"| EX5
    B2 -->|"OAuth"| EX2
    B2 -->|"Calendar_API"| EX1

    B3 -->|"Search_Query"| EX3

    A6 -->|"Schedule_Event"| EX1
    A4 -->|"Search_Data"| EX3

    B1 -->|"Response"| F1
    B1 -->|"Response"| F2
    B1 -->|"Response"| F3

    %% Styles
    classDef frontend fill:#b3cde0,stroke:#005b96,stroke-width:2px;
    classDef backend fill:#fbb4ae,stroke:#d95f02,stroke-width:2px;
    classDef external fill:#ccebc5,stroke:#1b947a,stroke-width:2px;

    class U external;
    class F1,F2,F3,F4,F5 frontend;
    class B1,B2,B3,A1,A2,A3,A4,A5,A6 backend;
    class EX1,EX2,EX3,EX4,EX5 external;

    %% Click Events for Frontend Components
    click F1 "https://github.com/sfkunal/chronos/blob/main/chronos-frontend/src/app/dashboard/page.jsx"
    click F2 "https://github.com/sfkunal/chronos/blob/main/chronos-frontend/src/app/lee/page.js"
    click F3 "https://github.com/sfkunal/chronos/blob/main/chronos-frontend/src/app/neha/page.js"
    click F4 "https://github.com/sfkunal/chronos/tree/main/chronos-frontend/src/components"
    click F5 "https://github.com/sfkunal/chronos/tree/main/chronos-frontend/src/hooks"

    %% Click Events for Backend Components
    click B1 "https://github.com/sfkunal/chronos/blob/main/chronos-backend/app.py"
    click B2 "https://github.com/sfkunal/chronos/blob/main/chronos-backend/groq_engine.py"
    click B3 "https://github.com/sfkunal/chronos/blob/main/chronos-backend/search_engine.py"
```
