# 333ian/taskful-api architecture

> Architecture diagram of the GitHub repository 333ian/taskful-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/333ian/taskful-api
- Repository: https://github.com/333ian/taskful-api

## Overview

Taskful API is a collaborative task-management backend. A client reaches account, house, and task endpoints; users manage profiles and house membership, then create task lists, tasks, and attachments within a house. Task status changes support progress tracking and point awards, while a scheduled job recalculates house statistics. The graph follows documented API routing and sampled module references; several implementation details, including social login, cloud storage, and point-signal behavior, are documented but not fully shown in the excerpts.

Main entry points: [`src/taskful_api/urls.py`](https://github.com/333ian/taskful-api/blob/master/src/taskful_api/urls.py) (API URL config), [`src/task/viewsets.py`](https://github.com/333ian/taskful-api/blob/master/src/task/viewsets.py) (Task API), [`src/house/viewsets.py`](https://github.com/333ian/taskful-api/blob/master/src/house/viewsets.py) (House API), [`src/users/viewsets.py`](https://github.com/333ian/taskful-api/blob/master/src/users/viewsets.py) (User API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API routing"]
  node_urls["API URL config<br/>[urls.py]"]
  node_user_routes["User routes<br/>[router.py]"]
  node_house_routes["House routes<br/>[router.py]"]
  node_task_routes["Task routes<br/>[router.py]"]
end

subgraph group_identity["Identity"]
  node_users_api["User API<br/>[viewsets.py]"]
  node_user_serializers["User serializers<br/>[serializers.py]"]
  node_profiles[("User profiles<br/>[models.py]")]
  node_oauth["OAuth services"]
end

subgraph group_collaboration["House collaboration"]
  node_houses_api["House API<br/>[viewsets.py]"]
  node_house_serializers["House serializers<br/>[serializers.py]"]
  node_houses[("Houses<br/>[models.py]")]
end

subgraph group_work["Tasks and progress"]
  node_tasks_api["Task API<br/>[viewsets.py]"]
  node_task_serializers["Task serializers<br/>[serializers.py]"]
  node_task_models[("Lists, tasks, attachments<br/>[models.py]")]
  node_task_signals["Task point signals<br/>[signals.py]"]
end

subgraph group_operations["Statistics and storage"]
  node_stats_job["Daily stats job<br/>[tasks.py]"]
  node_cloud_storage["Google Cloud Storage"]
end

node_client(("API client"))

node_client -->|"calls API"| node_urls
node_urls -->|"routes to"| node_user_routes
node_urls -->|"routes to"| node_house_routes
node_urls -->|"routes to"| node_task_routes
node_user_routes -->|"registers"| node_users_api
node_house_routes -->|"registers"| node_houses_api
node_task_routes -->|"registers"| node_tasks_api
node_users_api -->|"uses"| node_user_serializers
node_user_serializers -->|"serializes"| node_profiles
node_houses_api -->|"uses"| node_house_serializers
node_house_serializers -->|"serializes"| node_houses
node_houses_api -->|"queries and updates"| node_houses
node_tasks_api -->|"uses"| node_task_serializers
node_task_serializers -->|"serializes"| node_task_models
node_tasks_api -->|"queries and updates"| node_task_models
node_tasks_api -.->|"status change triggers"| node_task_signals
node_stats_job -->|"updates statistics"| node_houses
node_stats_job -->|"counts tasks"| node_task_models
node_oauth -.->|"supports login"| node_users_api
node_client -.->|"uploads media"| node_cloud_storage

click node_urls "https://github.com/333ian/taskful-api/blob/master/src/taskful_api/urls.py"
click node_user_routes "https://github.com/333ian/taskful-api/blob/master/src/users/router.py"
click node_house_routes "https://github.com/333ian/taskful-api/blob/master/src/house/router.py"
click node_task_routes "https://github.com/333ian/taskful-api/blob/master/src/task/router.py"
click node_users_api "https://github.com/333ian/taskful-api/blob/master/src/users/viewsets.py"
click node_user_serializers "https://github.com/333ian/taskful-api/blob/master/src/users/serializers.py"
click node_profiles "https://github.com/333ian/taskful-api/blob/master/src/users/models.py"
click node_houses_api "https://github.com/333ian/taskful-api/blob/master/src/house/viewsets.py"
click node_house_serializers "https://github.com/333ian/taskful-api/blob/master/src/house/serializers.py"
click node_houses "https://github.com/333ian/taskful-api/blob/master/src/house/models.py"
click node_tasks_api "https://github.com/333ian/taskful-api/blob/master/src/task/viewsets.py"
click node_task_serializers "https://github.com/333ian/taskful-api/blob/master/src/task/serializers.py"
click node_task_models "https://github.com/333ian/taskful-api/blob/master/src/task/models.py"
click node_task_signals "https://github.com/333ian/taskful-api/blob/master/src/task/signals.py"
click node_stats_job "https://github.com/333ian/taskful-api/blob/master/src/background_jobs/tasks.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_urls,node_user_routes,node_house_routes,node_task_routes,node_client toneBlue
class node_users_api,node_user_serializers,node_profiles,node_oauth toneAmber
class node_houses_api,node_house_serializers,node_houses toneMint
class node_tasks_api,node_task_serializers,node_task_models,node_task_signals toneRose
class node_stats_job,node_cloud_storage toneIndigo
```

## Components

### API routing

- [API URL config](https://github.com/333ian/taskful-api/blob/master/src/taskful_api/urls.py): `src/taskful_api/urls.py`
- [User routes](https://github.com/333ian/taskful-api/blob/master/src/users/router.py): `src/users/router.py`
- [House routes](https://github.com/333ian/taskful-api/blob/master/src/house/router.py): `src/house/router.py`
- [Task routes](https://github.com/333ian/taskful-api/blob/master/src/task/router.py): `src/task/router.py`

### Identity

- [User API](https://github.com/333ian/taskful-api/blob/master/src/users/viewsets.py): `src/users/viewsets.py`
- [User serializers](https://github.com/333ian/taskful-api/blob/master/src/users/serializers.py): `src/users/serializers.py`
- [User profiles](https://github.com/333ian/taskful-api/blob/master/src/users/models.py): `src/users/models.py`
- **OAuth services**

### House collaboration

- [House API](https://github.com/333ian/taskful-api/blob/master/src/house/viewsets.py): `src/house/viewsets.py`
- [House serializers](https://github.com/333ian/taskful-api/blob/master/src/house/serializers.py): `src/house/serializers.py`
- [Houses](https://github.com/333ian/taskful-api/blob/master/src/house/models.py): `src/house/models.py`

### Tasks and progress

- [Task API](https://github.com/333ian/taskful-api/blob/master/src/task/viewsets.py): `src/task/viewsets.py`
- [Task serializers](https://github.com/333ian/taskful-api/blob/master/src/task/serializers.py): `src/task/serializers.py`
- [Lists, tasks, attachments](https://github.com/333ian/taskful-api/blob/master/src/task/models.py): `src/task/models.py`
- [Task point signals](https://github.com/333ian/taskful-api/blob/master/src/task/signals.py): `src/task/signals.py`

### Statistics and storage

- [Daily stats job](https://github.com/333ian/taskful-api/blob/master/src/background_jobs/tasks.py): `src/background_jobs/tasks.py`
- **Google Cloud Storage**

### Other components

- **API client**

## Connections

- API client → API URL config: calls API (evidence: `README.md`)
- API URL config → User routes: routes to (evidence: `src/taskful_api/urls.py`)
- API URL config → House routes: routes to (evidence: `src/taskful_api/urls.py`)
- API URL config → Task routes: routes to (evidence: `src/taskful_api/urls.py`)
- User routes → User API: registers (evidence: `src/users/router.py`)
- House routes → House API: registers (evidence: `src/house/router.py`)
- Task routes → Task API: registers (evidence: `src/task/router.py`)
- User API → User serializers: uses (evidence: `src/users/viewsets.py`)
- User serializers → User profiles: serializes (evidence: `src/users/serializers.py`)
- House API → House serializers: uses (evidence: `src/house/viewsets.py`)
- House serializers → Houses: serializes (evidence: `src/house/serializers.py`)
- House API → Houses: queries and updates (evidence: `src/house/viewsets.py`)
- Task API → Task serializers: uses (evidence: `src/task/viewsets.py`)
- Task serializers → Lists, tasks, attachments: serializes (evidence: `src/task/serializers.py`)
- Task API → Lists, tasks, attachments: queries and updates (evidence: `src/task/viewsets.py`)
- Task API → Task point signals: status change triggers
- Daily stats job → Houses: updates statistics (evidence: `src/background_jobs/tasks.py`)
- Daily stats job → Lists, tasks, attachments: counts tasks (evidence: `src/background_jobs/tasks.py`)
- OAuth services → User API: supports login (evidence: `README.md`)
- API client → Google Cloud Storage: uploads media (evidence: `README.md`)
