# garezin86-pixel/spisoc_del architecture

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

- Interactive diagram: https://gitdiagram.com/garezin86-pixel/spisoc_del
- Repository: https://github.com/garezin86-pixel/spisoc_del

## Overview

Spisok Del is a task-management product with a React web client, FastAPI backend, Telegram bot, and admin interface. The main workflow is a user creating or managing tasks through a client, with backend services applying business rules and repositories persisting changes. Separate capabilities cover task planning, teamwork and chat, reporting, files, and account security. The README documents the broader architecture and features; sampled source confirms selected auth, storage, task-repository, WebSocket, and client interactions, so unsampled feature wiring is shown only at documented layer boundaries.

Main entry points: [`src/routers/tasks_router.py`](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/routers/tasks_router.py) (API routers), [`src/repositories/task_repository.py`](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/repositories/task_repository.py) (Data repositories), [`src/services/active_storage.py`](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/active_storage.py) (Storage selector), [`frontend/src/App.jsx`](https://github.com/garezin86-pixel/spisoc_del/blob/main/frontend/src/App.jsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User clients"]
  node_web_app["React application<br/>[App.jsx]"]
  node_web_api["API client<br/>[api.js]"]
  node_bot_handlers["Bot workflows<br/>[tasks.py]"]
  node_admin["Admin interface<br/>[task_admin.py]"]
end

subgraph group_backend["API and domain"]
  node_api_app["FastAPI application<br/>[main.py]"]
  node_api_routes["API routers<br/>[tasks_router.py]"]
  node_auth["Authentication<br/>[auth_service.py]"]
  node_task_domain["Task lifecycle<br/>[task_service.py]"]
  node_planning["Planning features"]
  node_team_domain["Projects and groups<br/>[project_service.py]"]
  node_templates["Task templates"]
  node_analytics["Analytics"]
end

subgraph group_persistence["Persistence"]
  node_task_repo["Data repositories<br/>[task_repository.py]"]
  node_models["Domain models<br/>[task.py]"]
  node_postgres[("PostgreSQL")]
end

subgraph group_collaboration["Collaboration"]
  node_chat["Team chat<br/>[chat_service.py]"]
  node_attachments["Attachment service"]
  node_active_storage["Storage selector<br/>[active_storage.py]"]
  node_local_storage["Local file storage"]
  node_r2_storage["Cloudflare R2<br/>[storage_service.py]"]
end

subgraph group_platform["Platform services"]
  node_notifications["Notifications and push<br/>[notifications.py]"]
  node_realtime["WebSocket hub<br/>[ws_manager.py]"]
  node_scheduler["Reminder scheduler<br/>[main.py]"]
  node_redis[("Redis")]
end

node_browser(("Browser user"))
node_telegram_user(("Telegram user"))
node_telegram_service(("Telegram platform"))
node_groq(("Groq voice AI"))

node_browser -->|"uses"| node_web_app
node_web_app -->|"requests"| node_web_api
node_web_api -->|"calls"| node_api_routes
node_api_app -->|"serves"| node_api_routes
node_api_routes -->|"delegates auth"| node_auth
node_api_routes -->|"delegates tasks"| node_task_domain
node_api_routes -->|"delegates planning"| node_planning
node_api_routes -->|"delegates teams"| node_team_domain
node_api_routes -->|"delegates templates"| node_templates
node_api_routes -->|"delegates analytics"| node_analytics
node_task_domain -->|"queries and updates"| node_task_repo
node_planning -->|"queries"| node_task_repo
node_team_domain -->|"persists data"| node_task_repo
node_templates -->|"persists data"| node_task_repo
node_analytics -->|"queries"| node_task_repo
node_task_repo -->|"maps records"| node_models
node_task_repo -->|"reads and writes"| node_postgres
node_telegram_user -->|"sends messages"| node_telegram_service
node_telegram_service -->|"dispatches"| node_bot_handlers
node_bot_handlers -->|"uses unit of work"| node_task_repo
node_admin -->|"administers data"| node_postgres
node_api_routes -->|"delegates chat"| node_chat
node_api_routes -->|"delegates files"| node_attachments
node_attachments -->|"stores files"| node_active_storage
node_active_storage -->|"selects active backend"| node_local_storage
node_active_storage -.->|"alternative backend"| node_r2_storage
node_api_routes -->|"delegates notifications"| node_notifications
node_api_routes -->|"dispatches events"| node_realtime
node_scheduler -->|"uses cache"| node_redis
node_auth -->|"stores token state"| node_redis
node_telegram_service -.->|"voice requests"| node_groq

click node_web_app "https://github.com/garezin86-pixel/spisoc_del/blob/main/frontend/src/App.jsx"
click node_web_api "https://github.com/garezin86-pixel/spisoc_del/blob/main/frontend/src/api.js"
click node_bot_handlers "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/bot/handlers/tasks.py"
click node_admin "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/admin/views/task_admin.py"
click node_api_app "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/main.py"
click node_api_routes "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/routers/tasks_router.py"
click node_auth "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/auth_service.py"
click node_task_domain "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/task_service.py"
click node_planning "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/calendar_service.py"
click node_team_domain "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/project_service.py"
click node_analytics "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/analytics_service.py"
click node_task_repo "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/repositories/task_repository.py"
click node_models "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/models/task.py"
click node_chat "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/chat_service.py"
click node_attachments "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/attachment_service.py"
click node_active_storage "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/active_storage.py"
click node_local_storage "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/local_storage_service.py"
click node_r2_storage "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/storage_service.py"
click node_notifications "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/notifications.py"
click node_realtime "https://github.com/garezin86-pixel/spisoc_del/blob/main/src/core/ws_manager.py"
click node_scheduler "https://github.com/garezin86-pixel/spisoc_del/blob/main/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_web_app,node_web_api,node_bot_handlers,node_admin,node_browser,node_telegram_user toneBlue
class node_api_app,node_api_routes,node_auth,node_task_domain,node_planning,node_team_domain,node_templates,node_analytics toneAmber
class node_task_repo,node_models,node_postgres toneMint
class node_chat,node_attachments,node_active_storage,node_local_storage,node_r2_storage toneRose
class node_notifications,node_realtime,node_scheduler,node_redis,node_telegram_service,node_groq toneIndigo
```

## Components

### User clients

- [React application](https://github.com/garezin86-pixel/spisoc_del/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/garezin86-pixel/spisoc_del/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Bot workflows](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/bot/handlers/tasks.py): `src/bot/handlers/tasks.py`
- [Admin interface](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/admin/views/task_admin.py): `src/admin/views/task_admin.py`

### API and domain

- [FastAPI application](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/main.py): `src/main.py`
- [API routers](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/routers/tasks_router.py): `src/routers/tasks_router.py`
- [Authentication](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/auth_service.py): `src/services/auth_service.py`
- [Task lifecycle](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/task_service.py): `src/services/task_service.py`
- [Planning features](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/calendar_service.py): `src/services/calendar_service.py`
- [Projects and groups](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/project_service.py): `src/services/project_service.py`
- **Task templates**
- [Analytics](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/analytics_service.py): `src/services/analytics_service.py`

### Persistence

- [Data repositories](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/repositories/task_repository.py): `src/repositories/task_repository.py`
- [Domain models](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/models/task.py): `src/models/task.py`
- **PostgreSQL**

### Collaboration

- [Team chat](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/chat_service.py): `src/services/chat_service.py`
- [Attachment service](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/attachment_service.py): `src/services/attachment_service.py`
- [Storage selector](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/active_storage.py): `src/services/active_storage.py`
- [Local file storage](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/local_storage_service.py): `src/services/local_storage_service.py`
- [Cloudflare R2](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/storage_service.py): `src/services/storage_service.py`

### Platform services

- [Notifications and push](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/services/notifications.py): `src/services/notifications.py`
- [WebSocket hub](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/core/ws_manager.py): `src/core/ws_manager.py`
- [Reminder scheduler](https://github.com/garezin86-pixel/spisoc_del/blob/main/src/main.py): `src/main.py`
- **Redis**

### Other components

- **Browser user**
- **Telegram user**
- **Telegram platform**
- **Groq voice AI**

## Connections

- Browser user → React application: uses
- React application → API client: requests
- API client → API routers: calls
- FastAPI application → API routers: serves
- API routers → Authentication: delegates auth
- API routers → Task lifecycle: delegates tasks
- API routers → Planning features: delegates planning
- API routers → Projects and groups: delegates teams
- API routers → Task templates: delegates templates
- API routers → Analytics: delegates analytics
- Task lifecycle → Data repositories: queries and updates
- Planning features → Data repositories: queries
- Projects and groups → Data repositories: persists data
- Task templates → Data repositories: persists data
- Analytics → Data repositories: queries
- Data repositories → Domain models: maps records
- Data repositories → PostgreSQL: reads and writes
- Telegram user → Telegram platform: sends messages
- Telegram platform → Bot workflows: dispatches
- Bot workflows → Data repositories: uses unit of work
- Admin interface → PostgreSQL: administers data
- API routers → Team chat: delegates chat
- API routers → Attachment service: delegates files
- Attachment service → Storage selector: stores files
- Storage selector → Local file storage: selects active backend
- Storage selector → Cloudflare R2: alternative backend
- API routers → Notifications and push: delegates notifications
- API routers → WebSocket hub: dispatches events
- Reminder scheduler → Redis: uses cache
- Authentication → Redis: stores token state
- Telegram platform → Groq voice AI: voice requests