# srinivas917/taskingo architecture

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

- Interactive diagram: https://gitdiagram.com/srinivas917/taskingo
- Repository: https://github.com/srinivas917/taskingo

## Overview

##### Model the intended product architecture (goal/task tracking + AI assistance) clearly.
2) **Leave implementation choices as placeholders** (e.g., “Backend API (TBD: Node/FastAPI/etc.)”) until code is available.

##### Backend gathers context
- active goal
- open tasks
- progress history
- preferences/constraints
##### AI output is parsed into structured tasks
- Tasks
- reorder/prioritize
- propose deadlines

##### Reminder / check-in flow (worker)
- Scheduler triggers:
- daily summary
- overdue reminder
- “you haven’t progressed” nudge
- Worker fetches user schedule/preferences → sends notification

##### Architectural patterns to highlight (even before code exists)
Given the product description, call these out visually:

- **Clean separation between Domain (goals/tasks) and AI integration**
- AI should be an “advisor,” not the source of truth for task state.
- **Event-like progress tracking**
- Task state changes can be stored as events (optional), enabling analytics.
- **Asynchronous background processing**
- reminders, summaries, heavy AI tasks, embeddings, analytics.
- **Auditability**
- store AI prompts/responses (with redaction) for debugging and safety.

##### Technologies to include (how to label without guessing)
Since there’s no code to confirm stack, label with **intent + placeholder**:

- “Client App (Web/Mobile — TBD)”
- “Backend API (REST/GraphQL — TBD)”
- “Database (SQL/NoSQL — TBD)”
- “LLM Provider (OpenAI/Anthropic/Local — TBD)”
- “Notifications (Email/SMS/Push — TBD)”

##### What you need next to make it truly “most accurate”
Right now, accuracy is limited by missing code. To finalize:
- Actual folders/files once they exist (e.g., `frontend/`, `backend/`, `services/ai/`, `db/`, `infra/`).
- Confirm:
- single service vs microservices
- storage type
- whether AI is synchronous user-triggered vs scheduled
- whether there’s a queue (SQS/RabbitMQ/Kafka)
- auth approach

- Goal/task domain as the core
- AI as an integration with orchestration, parsing, and audit trail
- Background jobs for reminders/summaries
- Strong, explicit data flows (CRUD + AI suggestion lifecycle)
- Placeholders for stack choices until code appears

This gives maximum detail without guessing implementation details that aren’t in the repository yet.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% LEVEL 1 — CONTEXT
  %% =========================
  subgraph L1["Context (C4 Level 1)"]
    U["User"]:::external

    subgraph SYS1["TaskinGo System"]
      TSG1["TaskinGo (AI goal & task tracker)"]:::system
    end

    LLM["LLM Provider (OpenAI/Anthropic/Local — TBD)"]:::external
    AUTH["Auth Provider (OAuth — TBD)"]:::external
    NOTIF["Notification Providers (Email/SMS/Push — TBD)"]:::external
    CAL["Calendar Integration (Google/Outlook — TBD)"]:::external

    U -->|"uses"| TSG1
    TSG1 -->|"calls"| LLM
    TSG1 -->|"auth_via"| AUTH
    TSG1 -->|"sends_notifications"| NOTIF
    TSG1 -->|"syncs_events"| CAL
  end

  %% =========================
  %% LEVEL 2 — CONTAINERS
  %% =========================
  subgraph L2["Container View (C4 Level 2)"]
    U2["User"]:::external

    subgraph SYS2["TaskinGo (Owned Boundary)"]
      CLIENT["Client App (Web/Mobile — TBD)"]:::client

      subgraph API_BOUNDARY["Backend Platform"]
        API["Backend API (REST/GraphQL — TBD)"]:::service
        AI_SVC["AI Orchestrator / AI Service (TBD)"]:::service
        WORKER["Background Worker / Scheduler (TBD)"]:::service
        CACHE["Cache (Sessions/Hot views — Optional)"]:::cache
        OBS["Observability (Logs/Metrics/Tracing — TBD)"]:::observability
        SECRETS["Secrets/Config (LLM keys, notif creds — TBD)"]:::secrets
        DB[("Database (SQL/NoSQL — TBD)")]:::db
      end
    end

    LLM2["LLM Provider (External)"]:::external
    AUTH2["Auth Provider (External)"]:::external
    NOTIF2["Notification Providers (External)"]:::external
    CAL2["Calendar Integration (External)"]:::external

    U2 -->|"interacts"| CLIENT
    CLIENT -->|"HTTP_API"| API

    API -->|"read_write"| DB
    API -.->|"cache_get_set"| CACHE

    API -->|"orchestrate_ai"| AI_SVC
    AI_SVC -->|"completion"| LLM2

    API -->|"auth_callbacks"| AUTH2
    API -->|"calendar_sync"| CAL2

    WORKER -.->|"scheduled_jobs"| API
    WORKER -->|"read_write"| DB
    WORKER -->|"send"| NOTIF2

    API -->|"emit_telemetry"| OBS
    WORKER -->|"emit_telemetry"| OBS
    AI_SVC -->|"emit_telemetry"| OBS
    SECRETS -.->|"provides_config"| API
    SECRETS -.->|"provides_config"| WORKER
    SECRETS -.->|"provides_config"| AI_SVC
  end

  %% =========================
  %% LEVEL 3 — COMPONENTS (Backend + AI)
  %% =========================
  subgraph L3["Component View (C4 Level 3) — Backend API & AI Integration"]
    subgraph API3["Backend API (TBD)"]
      AUTHM["Auth Module (JWT/Session/OAuth callbacks)"]:::component
      USERP["User Profile Module (prefs, schedule, constraints)"]:::component

      GOALS["Goal Management (create/update goals)"]:::component
      TASKS["Task Management (CRUD, status, dependencies)"]:::component
      PROG["Progress Tracking (events, logs, streaks)"]:::component
      PLAN["Recommendation / Planning (today plan, prioritization rules)"]:::component

      NOTIFSVC["Notification Service (message builder/router)"]:::component
      RL["Rate Limiter / Quotas (LLM + API)"]:::component

      AIGW["AI Integration Facade (API→AI service boundary)"]:::component
    end

    subgraph AI3["AI Orchestrator / AI Service (TBD)"]
      PROMPT["AI Prompt Builder (goal/task/history/prefs context)"]:::ai
      GUARD["Safety/Guardrails + Policy checks"]:::ai
      PARSER["AI Response Parser (normalize→structured suggestions)"]:::ai
      AUDIT["AI Audit Trail (redaction, versioning, debug)"]:::ai
    end

    subgraph DATA3["Conceptual Data Model (Stores/Tables — TBD)"]
      USERS[("Users")]:::db
      GOALST[("Goals")]:::db
      TASKST[("Tasks")]:::db
      DEPS[("TaskDependencies (optional)")]:::db
      EVENTS[("ProgressEvents")]:::db
      NOTIFT[("Notifications")]:::db
      SUGG[("AISuggestions")]:::db
      FEED[("AIFeedback")]:::db
    end

    EXT_LLM3["LLM Provider (External)"]:::external
    EXT_NOTIF3["Notification Providers (External)"]:::external

    %% --- Core CRUD flow
    AUTHM -->|"read_write"| USERS
    USERP -->|"read_write"| USERS

    GOALS -->|"read_write"| GOALST
    TASKS -->|"read_write"| TASKST
    TASKS -->|"read_write"| DEPS
    PROG -->|"append_event"| EVENTS
    NOTIFSVC -->|"persist"| NOTIFT

    %% --- AI suggestion flow
    PLAN -->|"needs_context"| GOALS
    PLAN -->|"needs_context"| TASKS
    PLAN -->|"needs_context"| PROG

    AIGW -->|"build_prompt"| PROMPT
    PROMPT -->|"apply_policies"| GUARD
    GUARD -->|"request_completion"| EXT_LLM3
    EXT_LLM3 -->|"raw_output"| PARSER
    PARSER -->|"store_suggestions"| SUGG
    AUDIT -->|"store_prompt_response"| SUGG
    PARSER -->|"capture_feedback"| FEED

    %% --- Notifications flow
    NOTIFSVC -->|"send"| EXT_NOTIF3

    %% --- Cross-cutting
    RL -.->|"protects"| AIGW
    RL -.->|"protects"| AUTHM
  end

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click TSG1 "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click CLIENT "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click API "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click AI_SVC "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click WORKER "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click DB "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click OBS "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click SECRETS "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click AUTHM "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click GOALS "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click TASKS "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click PROG "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click PLAN "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click PROMPT "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click PARSER "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click AUDIT "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click NOTIFSVC "https://github.com/srinivas917/taskingo/blob/main/README.md"
  click RL "https://github.com/srinivas917/taskingo/blob/main/README.md"

  %% =========================
  %% Styles
  %% =========================
  classDef system fill:#E5E7EB,stroke:#374151,stroke-width:2px,color:#111827
  classDef client fill:#DBEAFE,stroke:#1D4ED8,stroke-width:2px,color:#0F172A
  classDef service fill:#DCFCE7,stroke:#16A34A,stroke-width:2px,color:#052E16
  classDef component fill:#BBF7D0,stroke:#15803D,stroke-width:1.5px,color:#052E16
  classDef ai fill:#EDE9FE,stroke:#6D28D9,stroke-width:2px,color:#1F1147
  classDef db fill:#FEF9C3,stroke:#CA8A04,stroke-width:2px,color:#422006
  classDef cache fill:#FFF7ED,stroke:#C2410C,stroke-width:2px,color:#431407
  classDef observability fill:#E0F2FE,stroke:#0369A1,stroke-width:2px,color:#082F49
  classDef secrets fill:#FCE7F3,stroke:#BE185D,stroke-width:2px,color:#500724
  classDef external fill:#F3F4F6,stroke:#6B7280,stroke-width:2px,stroke-dasharray:4 4,color:#111827
```
