# besessener/procrastinationbuddy architecture

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

- Interactive diagram: https://gitdiagram.com/besessener/procrastinationbuddy
- Repository: https://github.com/besessener/procrastinationbuddy

## Overview

##### Project type and purpose
- This is a Dockerized, full-stack Python application called “Procrastination Buddy.”
- Purpose: deliver a Streamlit-based UI in the browser that fetches silly “procrastination tasks” from a Flask backend, which uses an Ollama AI model to generate tasks and persists tasks/settings in a PostgreSQL database.

##### File structure
- Top-level directories:
- backend/ – Flask app source (routes, services, DB code), Dockerfile, pytest tests
- frontend/ – Streamlit app source (UI components, utils), Dockerfile, pytest tests
- tests/ – API collections (Bruno .bru files) and E2E tests (Playwright)
- docs/ – architecture and UI screenshots
- compose.yaml – Docker Compose orchestration
- buddy.sh – helper script to start/stop services and run tests
- .github/workflows – CI (auto-merge, quality gate)
- Architectural hints: two containerized services (frontend, backend), an external AI model service, and a PostgreSQL data store.

##### README for additional insights
- Confirms four key services in Docker Compose:
1. Frontend (Streamlit)
2. Backend (Flask)
3. Ollama AI model
4. PostgreSQL database
- Tests include Flask unit tests, API test collections, and Playwright E2E.

- User’s Web Browser (UI)
- Streamlit Frontend Container
- Flask Backend Container
- Ollama AI Model Service Container
- PostgreSQL Database Container
- Orchestrator: Docker Compose (compose.yaml)
- (Optional) CI/CD: GitHub Actions pipelines
b. Relationships and data flows:
- Browser ↔ Frontend: HTTP(S) requests/responses for UI rendering and user interactions
- Frontend → Backend: REST API calls (tasks, settings endpoints)
- Backend → Ollama: RPC or HTTP call to the AI model for task generation
- Backend ↔ PostgreSQL: SQL queries over TCP to store/retrieve tasks/settings
- buddy.sh → Docker Compose: CLI orchestration of service lifecycle
c. Architectural patterns and principles:
- Layered microservices style: UI layer (Streamlit), API layer (Flask), Service/AI layer (Ollama), Data layer (Postgres)
- Separation of concerns: UI rendering vs. business logic vs. persistence vs. model inference
- Containerization for consistent environments
d. Key technologies/frameworks:
- Python, Streamlit, Flask
- Docker, Docker Compose, bash script (buddy.sh)
- Ollama model server
- PostgreSQL
- Testing: pytest, Playwright, Bruno collections

##### Essential details
- Inter-service protocols and data-flow directions are explicitly shown

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers and Components
    subgraph "User Layer" 
        direction TB
        Browser["User Web Browser"]:::browser
    end

    subgraph "Docker Compose Orchestrator" 
        direction TB
        Compose["Docker Compose\n(compose.yaml)"]:::orchestration
        BuddySH["buddy.sh"]:::orchestration
    end

    Compose -->|orchestrates| FrontendService
    BuddySH -->|invokes| Compose

    subgraph "Service Layer" 
        direction TB
        subgraph "Frontend Service" 
            direction TB
            FrontendService["Streamlit Frontend\n(port 8501)"]:::frontend
            FE_App["app.py"]:::frontend
            FE_UI["ui modules"]:::frontend
            FE_Utils["tasks_api & settings_api"]:::frontend
        end

        subgraph "Backend Service" 
            direction TB
            BackendService["Flask Backend\n(port 5000)"]:::backend
            BE_App["app.py"]:::backend
            BE_Routes["routes tasks/settings"]:::backend
            BE_Services["services tasks/settings"]:::backend
            DB_Logic["db.py"]:::backend
        end

        subgraph "External AI Service" 
            direction TB
            Ollama["Ollama AI Model Service"]:::ai
            OL_Health["health.bru"]:::ai
            OL_List["list models.bru"]:::ai
            OL_Gen["generate.bru"]:::ai
        end

        subgraph "Database Layer" 
            direction TB
            Postgres["PostgreSQL Database"]:::db
        end
    end

    %% Data Flows
    Browser -->|HTTP requests| FrontendService
    FrontendService -->|REST API| BackendService
    BackendService -->|RPC/HTTP| Ollama
    BackendService -->|SQL over TCP| Postgres
    Ollama -->|response| BackendService
    Postgres -->|data| BackendService
    BackendService -->|API response| FrontendService
    FrontendService -->|render UI| Browser

    %% CI/CD and Tests
    subgraph "CI/CD Pipelines" 
        direction TB
        AutoMerge["auto-merge.yaml"]:::ci
        QualityGate["quality-gate.yaml"]:::ci
    end

    subgraph "Backend Unit Tests" 
        direction TB
        BE_Tests["backend/test/"]:::test
    end

    subgraph "Frontend Unit Tests" 
        direction TB
        FE_Tests["frontend/test/"]:::test
    end

    subgraph "API Collections" 
        direction TB
        API_Col["tests/api/collection.bru"]:::test
    end

    subgraph "E2E Tests" 
        direction TB
        E2E["tests/e2e/"]:::test
    end

    AutoMerge ---|triggers| Compose
    QualityGate ---|triggers| Compose

    BE_Tests -->|tests API & services| BackendService
    FE_Tests -->|tests UI utils| FrontendService
    API_Col -->|validates API| BackendService
    E2E -->|end-to-end tests| FrontendService

    %% Click Events
    click FrontendService "https://github.com/besessener/procrastinationbuddy/tree/main/frontend/"
    click FE_App "https://github.com/besessener/procrastinationbuddy/blob/main/frontend/src/app.py"
    click FE_UI "https://github.com/besessener/procrastinationbuddy/blob/main/frontend/src/ui/page_setup.py"
    click FE_UI "https://github.com/besessener/procrastinationbuddy/blob/main/frontend/src/ui/dialogs.py"
    click FE_UI "https://github.com/besessener/procrastinationbuddy/blob/main/frontend/src/ui/rendering.py"
    click FE_Utils "https://github.com/besessener/procrastinationbuddy/blob/main/frontend/src/utils/tasks_api.py"
    click FE_Utils "https://github.com/besessener/procrastinationbuddy/blob/main/frontend/src/utils/settings_api.py"

    click BackendService "https://github.com/besessener/procrastinationbuddy/tree/main/backend/"
    click BE_App "https://github.com/besessener/procrastinationbuddy/blob/main/backend/src/app.py"
    click BE_Routes "https://github.com/besessener/procrastinationbuddy/blob/main/backend/src/routes/tasks.py"
    click BE_Routes "https://github.com/besessener/procrastinationbuddy/blob/main/backend/src/routes/settings.py"
    click BE_Services "https://github.com/besessener/procrastinationbuddy/blob/main/backend/src/services/tasks.py"
    click BE_Services "https://github.com/besessener/procrastinationbuddy/blob/main/backend/src/services/settings.py"
    click DB_Logic "https://github.com/besessener/procrastinationbuddy/blob/main/backend/src/db/db.py"

    click Ollama "https://github.com/besessener/procrastinationbuddy/tree/main/tests/api/ollama/"
    click OL_Health "https://github.com/besessener/procrastinationbuddy/blob/main/tests/api/ollama/health.bru"
    click OL_List "https://github.com/besessener/procrastinationbuddy/blob/main/tests/api/ollama/list models.bru"
    click OL_Gen "https://github.com/besessener/procrastinationbuddy/blob/main/tests/api/ollama/generate.bru"

    click Compose "https://github.com/besessener/procrastinationbuddy/blob/main/compose.yaml"
    click BuddySH "https://github.com/besessener/procrastinationbuddy/blob/main/buddy.sh"

    click AutoMerge "https://github.com/besessener/procrastinationbuddy/blob/main/.github/workflows/auto-merge.yaml"
    click QualityGate "https://github.com/besessener/procrastinationbuddy/blob/main/.github/workflows/quality-gate.yaml"

    click BE_Tests "https://github.com/besessener/procrastinationbuddy/tree/main/backend/test/"
    click FE_Tests "https://github.com/besessener/procrastinationbuddy/tree/main/frontend/test/"
    click API_Col "https://github.com/besessener/procrastinationbuddy/blob/main/tests/api/collection.bru"
    click E2E "https://github.com/besessener/procrastinationbuddy/tree/main/tests/e2e/"

    %% Styles
    classDef browser fill:#A8DADC,stroke:#1D3557,color:#1D3557;
    classDef frontend fill:#457B9D,stroke:#1D3557,color:#F1FAEE;
    classDef backend fill:#2A9D8F,stroke:#1D3557,color:#F1FAEE;
    classDef ai fill:#E76F51,stroke:#9A031E,color:#F1FAEE;
    classDef db fill:#9D4EDD,stroke:#5A189A,color:#F1FAEE;
    classDef orchestration fill:#6C757D,stroke:#343A40,color:#F8F9FA;
    classDef ci fill:#6C757D,stroke:#343A40,color:#F8F9FA;
    classDef test fill:#F4A261,stroke:#E76F51,color:#1D3557;
```
