# maryumxx/todo-cloud-native-app architecture

> Architecture diagram of the GitHub repository maryumxx/todo-cloud-native-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maryumxx/todo-cloud-native-app
- Repository: https://github.com/maryumxx/todo-cloud-native-app

## Overview

TaskFlow is a web todo application with a separate AI-chatbot backend and frontend. The main workflow is a user authenticating in the web app, then managing tasks and calendar events through the API; the API applies user-scoped services and persists state. The repository also includes onboarding/profile capabilities, real-time task synchronization, chatbot task tools, recurring-task processing, and reminders. The README is empty, so these capabilities are inferred from the tree and sampled source; some links, especially frontend/API and background-service wiring, remain unverified.

Main entry points: [`todo-web-app/backend/src/main.py`](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/main.py) (REST API), [`todo-web-app/frontend/lib/api-client.ts`](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/lib/api-client.ts) (API client), [`todo-web-app/backend/src/db/connection.py`](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/db/connection.py) (Todo database), [`todo-web-app/backend/src/api/auth.py`](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/auth.py) (Authentication routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["TaskFlow web app<br/>[page.tsx]"]
  node_authui["Sign-in and onboarding<br/>[page.tsx]"]
  node_taskui["Task workspace<br/>[page.tsx]"]
  node_calendarui["Calendar<br/>[page.tsx]"]
  node_profileui["Profile<br/>[page.tsx]"]
  node_webclient["API client<br/>[api-client.ts]"]
  node_chatui["Chat interface<br/>[ChatInterface.tsx]"]
  node_chatclient["Chat API client<br/>[api-client.ts]"]
end

subgraph group_core["Todo API"]
  node_api["REST API<br/>[main.py]"]
  node_authroutes["Authentication routes<br/>[auth.py]"]
  node_authdeps["JWT identity<br/>[deps.py]"]
  node_authservice["Authentication service<br/>[auth_service.py]"]
  node_taskroutes["Task routes<br/>[tasks.py]"]
  node_taskservice["Task service<br/>[task_service.py]"]
  node_eventroutes["Event routes<br/>[events.py]"]
  node_eventservice["Event service<br/>[event_service.py]"]
  node_userroutes["User routes<br/>[users.py]"]
  node_userservice["User service<br/>[user_service.py]"]
  node_coredb[("Todo database<br/>[connection.py]")]
  node_ws["Live task sync<br/>[manager.py]"]
end

subgraph group_chatbot["AI assistant"]
  node_chatapi["Chat API<br/>[chat.py]"]
  node_agent["Chat agent<br/>[chat_agent.py]"]
  node_mcp["Task tool server<br/>[server.py]"]
  node_chatdb[("Chat database<br/>[connection.py]")]
  node_chatservices["Conversation and task services"]
end

subgraph group_background["Background services"]
  node_recurring["Recurring task worker<br/>[main.py]"]
  node_completion["Completion consumer<br/>[task_completed.py]"]
  node_rrule["Recurrence parsing<br/>[rrule_parser.py]"]
  node_occurrence["Occurrence generator"]
  node_reminders["Reminder service<br/>[main.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -.->|"offers sign-in"| node_authui
node_user -->|"manages tasks"| node_taskui
node_user -->|"views events"| node_calendarui
node_user -->|"edits profile"| node_profileui
node_taskui -.->|"requests data"| node_webclient
node_calendarui -.->|"requests data"| node_webclient
node_profileui -.->|"requests data"| node_webclient
node_webclient -.->|"calls API"| node_api
node_api -->|"registers routes"| node_authroutes
node_api -->|"registers routes"| node_taskroutes
node_api -->|"registers routes"| node_eventroutes
node_api -->|"registers routes"| node_userroutes
node_api -->|"initializes tables"| node_coredb
node_api -->|"uses manager"| node_ws
node_authroutes -->|"calls"| node_authservice
node_authroutes -->|"uses identity"| node_authdeps
node_authdeps -->|"retrieves user"| node_authservice
node_taskroutes -->|"requires identity"| node_authdeps
node_taskroutes -->|"calls"| node_taskservice
node_eventroutes -->|"calls"| node_eventservice
node_userroutes -->|"calls"| node_userservice
node_taskservice -.->|"reads and writes"| node_coredb
node_authservice -.->|"reads and writes"| node_coredb
node_eventservice -.->|"reads and writes"| node_coredb
node_user -.->|"chats"| node_chatui
node_chatui -.->|"sends messages"| node_chatclient
node_chatclient -.->|"calls"| node_chatapi
node_chatapi -->|"initializes tables"| node_chatdb
node_chatapi -.->|"delegates"| node_agent
node_agent -.->|"invokes tools"| node_mcp
node_mcp -->|"uses task service"| node_chatservices
node_chatservices -.->|"persists records"| node_chatdb
node_completion -.->|"parses recurrence"| node_rrule
node_completion -.->|"generates occurrences"| node_occurrence
node_recurring -.->|"handles events"| node_completion

click node_webapp "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/page.tsx"
click node_authui "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/(auth)/login/page.tsx"
click node_taskui "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/dashboard/tasks/page.tsx"
click node_calendarui "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/dashboard/calendar/page.tsx"
click node_profileui "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/dashboard/profile/page.tsx"
click node_webclient "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/lib/api-client.ts"
click node_api "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/main.py"
click node_authroutes "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/auth.py"
click node_authdeps "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/deps.py"
click node_authservice "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/auth_service.py"
click node_taskroutes "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/tasks.py"
click node_taskservice "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/task_service.py"
click node_eventroutes "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/events.py"
click node_eventservice "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/event_service.py"
click node_userroutes "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/users.py"
click node_userservice "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/user_service.py"
click node_coredb "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/db/connection.py"
click node_ws "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/websocket/manager.py"
click node_chatui "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/frontend/src/components/chatkit/ChatInterface.tsx"
click node_chatclient "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/frontend/src/lib/api-client.ts"
click node_chatapi "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/api/chat.py"
click node_agent "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/agents/chat_agent.py"
click node_mcp "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/mcp/server.py"
click node_chatdb "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/database/connection.py"
click node_chatservices "https://github.com/maryumxx/todo-cloud-native-app/tree/main/todo-web-app/chatbot/backend/src/services"
click node_recurring "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/main.py"
click node_completion "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/consumers/task_completed.py"
click node_rrule "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/rrule_parser.py"
click node_occurrence "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/services/occurrence_generator.py"
click node_reminders "https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/reminder-service/src/main.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_webapp,node_authui,node_taskui,node_calendarui,node_profileui,node_webclient,node_chatui,node_chatclient,node_user toneBlue
class node_api,node_authroutes,node_authdeps,node_authservice,node_taskroutes,node_taskservice,node_eventroutes,node_eventservice,node_userroutes,node_userservice,node_coredb,node_ws toneAmber
class node_chatapi,node_agent,node_mcp,node_chatdb,node_chatservices toneMint
class node_recurring,node_completion,node_rrule,node_occurrence,node_reminders toneRose
```

## Components

### Web experience

- [TaskFlow web app](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/page.tsx): `todo-web-app/frontend/app/page.tsx`
- [Sign-in and onboarding](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/(auth)/login/page.tsx): `todo-web-app/frontend/app/(auth)/login/page.tsx`
- [Task workspace](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/dashboard/tasks/page.tsx): `todo-web-app/frontend/app/dashboard/tasks/page.tsx`
- [Calendar](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/dashboard/calendar/page.tsx): `todo-web-app/frontend/app/dashboard/calendar/page.tsx`
- [Profile](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/app/dashboard/profile/page.tsx): `todo-web-app/frontend/app/dashboard/profile/page.tsx`
- [API client](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/frontend/lib/api-client.ts): `todo-web-app/frontend/lib/api-client.ts`
- [Chat interface](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/frontend/src/components/chatkit/ChatInterface.tsx): `todo-web-app/chatbot/frontend/src/components/chatkit/ChatInterface.tsx`
- [Chat API client](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/frontend/src/lib/api-client.ts): `todo-web-app/chatbot/frontend/src/lib/api-client.ts`

### Todo API

- [REST API](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/main.py): `todo-web-app/backend/src/main.py`
- [Authentication routes](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/auth.py): `todo-web-app/backend/src/api/auth.py`
- [JWT identity](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/deps.py): `todo-web-app/backend/src/api/deps.py`
- [Authentication service](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/auth_service.py): `todo-web-app/backend/src/services/auth_service.py`
- [Task routes](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/tasks.py): `todo-web-app/backend/src/api/tasks.py`
- [Task service](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/task_service.py): `todo-web-app/backend/src/services/task_service.py`
- [Event routes](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/events.py): `todo-web-app/backend/src/api/events.py`
- [Event service](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/event_service.py): `todo-web-app/backend/src/services/event_service.py`
- [User routes](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/api/users.py): `todo-web-app/backend/src/api/users.py`
- [User service](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/services/user_service.py): `todo-web-app/backend/src/services/user_service.py`
- [Todo database](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/db/connection.py): `todo-web-app/backend/src/db/connection.py`
- [Live task sync](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/backend/src/websocket/manager.py): `todo-web-app/backend/src/websocket/manager.py`

### AI assistant

- [Chat API](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/api/chat.py): `todo-web-app/chatbot/backend/src/api/chat.py`
- [Chat agent](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/agents/chat_agent.py): `todo-web-app/chatbot/backend/src/agents/chat_agent.py`
- [Task tool server](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/mcp/server.py): `todo-web-app/chatbot/backend/src/mcp/server.py`
- [Chat database](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/chatbot/backend/src/database/connection.py): `todo-web-app/chatbot/backend/src/database/connection.py`
- [Conversation and task services](https://github.com/maryumxx/todo-cloud-native-app/tree/main/todo-web-app/chatbot/backend/src/services): `todo-web-app/chatbot/backend/src/services`

### Background services

- [Recurring task worker](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/main.py): `todo-web-app/services/recurring-task/src/main.py`
- [Completion consumer](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/consumers/task_completed.py): `todo-web-app/services/recurring-task/src/consumers/task_completed.py`
- [Recurrence parsing](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/rrule_parser.py): `todo-web-app/services/recurring-task/src/rrule_parser.py`
- [Occurrence generator](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/recurring-task/src/services/occurrence_generator.py): `todo-web-app/services/recurring-task/src/services/occurrence_generator.py`
- [Reminder service](https://github.com/maryumxx/todo-cloud-native-app/blob/main/todo-web-app/services/reminder-service/src/main.py): `todo-web-app/services/reminder-service/src/main.py`

### Other components

- **User**

## Connections

- User → TaskFlow web app: uses (evidence: `todo-web-app/frontend/app/page.tsx`)
- TaskFlow web app → Sign-in and onboarding: offers sign-in
- User → Task workspace: manages tasks (evidence: `todo-web-app/frontend/app/dashboard/tasks/page.tsx`)
- User → Calendar: views events (evidence: `todo-web-app/frontend/app/dashboard/calendar/page.tsx`)
- User → Profile: edits profile (evidence: `todo-web-app/frontend/app/dashboard/profile/page.tsx`)
- Task workspace → API client: requests data
- Calendar → API client: requests data
- Profile → API client: requests data
- API client → REST API: calls API
- REST API → Authentication routes: registers routes (evidence: `todo-web-app/backend/src/main.py`)
- REST API → Task routes: registers routes (evidence: `todo-web-app/backend/src/main.py`)
- REST API → Event routes: registers routes (evidence: `todo-web-app/backend/src/main.py`)
- REST API → User routes: registers routes (evidence: `todo-web-app/backend/src/main.py`)
- REST API → Todo database: initializes tables (evidence: `todo-web-app/backend/src/main.py`)
- REST API → Live task sync: uses manager (evidence: `todo-web-app/backend/src/main.py`)
- Authentication routes → Authentication service: calls (evidence: `todo-web-app/backend/src/api/auth.py`)
- Authentication routes → JWT identity: uses identity (evidence: `todo-web-app/backend/src/api/auth.py`)
- JWT identity → Authentication service: retrieves user (evidence: `todo-web-app/backend/src/api/deps.py`)
- Task routes → JWT identity: requires identity (evidence: `todo-web-app/backend/src/api/tasks.py`)
- Task routes → Task service: calls (evidence: `todo-web-app/backend/src/api/tasks.py`)
- Event routes → Event service: calls (evidence: `todo-web-app/backend/src/api/events.py`)
- User routes → User service: calls (evidence: `todo-web-app/backend/src/api/users.py`)
- Task service → Todo database: reads and writes
- Authentication service → Todo database: reads and writes
- Event service → Todo database: reads and writes
- User → Chat interface: chats
- Chat interface → Chat API client: sends messages
- Chat API client → Chat API: calls
- Chat API → Chat database: initializes tables (evidence: `todo-web-app/chatbot/backend/src/main.py`)
- Chat API → Chat agent: delegates
- Chat agent → Task tool server: invokes tools
- Task tool server → Conversation and task services: uses task service (evidence: `todo-web-app/chatbot/backend/src/mcp/server.py`)
- Conversation and task services → Chat database: persists records
- Completion consumer → Recurrence parsing: parses recurrence
- Completion consumer → Occurrence generator: generates occurrences
- Recurring task worker → Completion consumer: handles events
