# juandarr/todo-react-django architecture

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

- Interactive diagram: https://gitdiagram.com/juandarr/todo-react-django
- Repository: https://github.com/juandarr/todo-react-django

## Overview

1. **High-level shape**
   - JoyFlow is a **single repository with two runtime tiers**: a **Django backend** and a **React + TypeScript frontend**.
   - The backend owns persistence, authentication, and the REST API; the frontend owns the interactive task-management UI.

2. **Backend boundary**
   - The Django project lives under `todo_react_django/` and the domain app under `todo/`.
   - `todo/` contains the core server-side layers: `models.py`, `serializers.py`, `views.py`, `urls.py`, `forms.py`, `signals.py`, and migrations.
   - Data is stored in a **SQL database** through Django ORM.

3. **Frontend boundary**
   - The React application is isolated in `jstoolchains/`.
   - Entry points are `src/index.tsx` and `src/App.tsx`, with the UI assembled from feature modules rather than a single monolith.
   - This frontend is built separately from Django using **Webpack** and **TailwindCSS**.

4. **Primary domain model**
   - The core business objects are **Lists**, **Todos/Tasks**, and **User settings / inbox behavior**.
   - The README shows the main product semantics: tasks have title, description, completion state, due date/time, priority, all-day flag, and optional list association; lists have title and archive behavior.
   - Migrations indicate the schema has evolved around list ordering, task ordering, inbox ownership, and all-day task support.

5. **Main user-facing subsystems**
   - `src/components/taskview/` implements the central task list experience: headers, task forms, task items, list rendering, and sortable task behavior.
   - `src/components/sidebar/` manages the list navigation and drag-and-drop ordering of lists.
   - `src/components/navbar/` provides the top-level app actions, including task creation entry points.
   - `src/components/modals/` contains create/edit/delete/profile/settings/logout/password-change flows, so modal state is a major UI boundary.

6. **Shared UI layer**
   - `src/components/ui/` contains reusable controls such as buttons, badges, checkbox, select, popover, calendar, datetime picker, emoji picker, text editor, tooltip, virtualization, and toasts.
   - This layer is the presentation foundation used across modals, forms, and task/list views.
   - The presence of virtualization and sortable items suggests the UI is optimized for larger task/list collections and drag-and-drop interactions.

7. **State management and UI orchestration**
   - `src/contexts/ModalContext.ts` and `src/contexts/UserContext.ts` centralize global cross-cutting UI state.
   - `src/reducers/listsReducer.ts` indicates list state is managed with reducer-style updates, likely to support reordering and list mutations consistently.
   - Custom hooks such as `useModelFetch`, `useOnlineStatus`, `useAutosizeTextArea`, and `useTextEditor` encapsulate view-specific behavior and data loading.

8. **Frontend-to-backend data flow**
   - The frontend talks to the backend through `src/lib/api.ts`, with types and contracts in `src/lib/customTypes.ts`.
   - The README and `schema.yml` show the API is **schema-driven**: OpenAPI is used to generate a typed client for the React app.
   - This creates a clear contract boundary: React components consume typed API calls, while Django serializers/views define the actual data surface.

9. **Authentication and user lifecycle**
   - The app uses Django’s auth system, with server-rendered registration/password templates under `templates/registration/`.
   - The frontend also includes profile, settings, password change, and logout modals, so user account management is split across server-rendered auth pages and in-app UI.
   - `UserContext` likely bridges authenticated user state into the React layer.

10. **Rendering and delivery model**
   - Django serves base HTML templates (`templates/base.html`, `templates/index.html`) and static assets from `static/`.
   - The React app is meant to mount into the Django-rendered page shell, making Django the delivery container for the SPA-like experience.
   - The presence of separate login/signup/password templates means the repo mixes a React app shell with classic Django auth pages.

11. **Styling and asset pipeline**
   - Tailwind is a first-class part of the frontend architecture via `tailwind.config.js` and `static/css/input.css`.
   - The frontend build stack also includes Babel/Webpack configuration and an OpenAPI generator config under `jstoolchains/`.
   - Static fonts and images live outside the React bundle, reinforcing the split between app code and server-delivered assets.

12. **Operational characteristics**
   - The README describes a development mode requiring three concurrent processes: Django server, Tailwind watch, and Webpack dev build.
   - That implies the app is composed at runtime from independently built frontend assets and backend API/content.
   - The architecture is therefore best drawn as: **browser/UI → React bundle → Django REST/API + auth pages → SQL database**, with shared contracts generated from OpenAPI and UI state managed in the React layer.

Main entry points: [`jstoolchains/src/App.tsx`](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/App.tsx) (Main app), [`todo`](https://github.com/juandarr/todo-react-django/tree/main/todo) (Domain app), [`jstoolchains/src/lib`](https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/lib) (Client data), [`jstoolchains/src/components/taskview/taskview.tsx`](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/components/taskview/taskview.tsx) (Task view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_spa_shell["App shell<br/>react entry<br/>[index.tsx]"]
  node_app_root["Main app<br/>react root<br/>[App.tsx]"]
  node_task_view["Task view<br/>feature<br/>[taskview.tsx]"]
  node_sidebar_nav["Sidebar<br/>feature<br/>[sidebar.tsx]"]
  node_top_nav["Navbar<br/>feature<br/>[navbar.tsx]"]
  node_modal_flows["Modals<br/>feature set"]
  node_ui_kit["UI kit<br/>shared components"]
  node_ui_state["UI state<br/>contexts"]
  node_list_state["List state<br/>reducer<br/>[listsReducer.ts]"]
end

subgraph group_backend["Backend"]
  node_django_project["Django project"]
  node_domain_app["Domain app<br/>django app"]
  node_models[("Models<br/>orm<br/>[models.py]")]
  node_api_layer["API layer<br/>rest<br/>[serializers.py]"]
  node_routing["Routing<br/>urls<br/>[urls.py]"]
  node_database[("SQL database<br/>storage")]
end

subgraph group_shared["Shared"]
  node_client_data["Client data<br/>api/client"]
  node_auth_pages["Auth pages<br/>templates"]
  node_shell_templates["Shell templates<br/>[base.html]"]
  node_build_pipeline["Build pipeline<br/>tooling<br/>[webpack.config.js]"]
  node_schema_contract["Schema contract<br/>openapi<br/>[schema.yml]"]
end

node_browser(("Browser<br/>client"))

node_browser -->|"loads"| node_shell_templates
node_shell_templates -->|"mounts"| node_spa_shell
node_spa_shell -->|"renders"| node_app_root
node_app_root -->|"shows"| node_task_view
node_app_root -->|"includes"| node_sidebar_nav
node_app_root -->|"includes"| node_top_nav
node_app_root -->|"opens"| node_modal_flows
node_task_view -->|"uses"| node_ui_kit
node_sidebar_nav -->|"uses"| node_ui_kit
node_modal_flows -->|"uses"| node_ui_kit
node_app_root -->|"shares state"| node_ui_state
node_app_root -->|"updates"| node_list_state
node_task_view -->|"fetches"| node_client_data
node_sidebar_nav -->|"fetches"| node_client_data
node_modal_flows -->|"mutates"| node_client_data
node_client_data -->|"follows"| node_schema_contract
node_schema_contract -->|"describes"| node_api_layer
node_django_project -->|"hosts"| node_domain_app
node_domain_app -->|"persists"| node_models
node_domain_app -->|"exposes"| node_api_layer
node_domain_app -->|"routes"| node_routing
node_models -->|"stores"| node_database
node_routing -->|"serves"| node_auth_pages
node_shell_templates -->|"packages"| node_build_pipeline
node_build_pipeline -->|"builds"| node_spa_shell

click node_spa_shell "https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/index.tsx"
click node_app_root "https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/App.tsx"
click node_task_view "https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/components/taskview/taskview.tsx"
click node_sidebar_nav "https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/components/sidebar/sidebar.tsx"
click node_top_nav "https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/components/navbar/navbar.tsx"
click node_modal_flows "https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/components/modals"
click node_ui_kit "https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/components/ui"
click node_ui_state "https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/contexts"
click node_client_data "https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/lib"
click node_list_state "https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/reducers/listsReducer.ts"
click node_django_project "https://github.com/juandarr/todo-react-django/tree/main/todo_react_django"
click node_domain_app "https://github.com/juandarr/todo-react-django/tree/main/todo"
click node_models "https://github.com/juandarr/todo-react-django/blob/main/todo/models.py"
click node_api_layer "https://github.com/juandarr/todo-react-django/blob/main/todo/serializers.py"
click node_routing "https://github.com/juandarr/todo-react-django/blob/main/todo/urls.py"
click node_auth_pages "https://github.com/juandarr/todo-react-django/tree/main/templates/registration"
click node_shell_templates "https://github.com/juandarr/todo-react-django/blob/main/templates/base.html"
click node_build_pipeline "https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/webpack.config.js"
click node_schema_contract "https://github.com/juandarr/todo-react-django/blob/main/schema.yml"

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_spa_shell,node_app_root,node_task_view,node_sidebar_nav,node_top_nav,node_modal_flows,node_ui_kit,node_ui_state,node_list_state toneBlue
class node_django_project,node_domain_app,node_models,node_api_layer,node_routing,node_database toneAmber
class node_client_data,node_auth_pages,node_shell_templates,node_build_pipeline,node_schema_contract toneMint
class node_browser toneNeutral
```

## Components

### Frontend

React + TypeScript application and UI architecture.

- [App shell](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/index.tsx): react entry · Mount point and top-level React composition. · `jstoolchains/src/index.tsx`
- [Main app](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/App.tsx): react root · Primary frontend router and orchestration component. · `jstoolchains/src/App.tsx`
- [Task view](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/components/taskview/taskview.tsx): feature · Central task-list experience and task editing flow. · `jstoolchains/src/components/taskview/taskview.tsx`
- [Sidebar](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/components/sidebar/sidebar.tsx): feature · List navigation and list ordering interactions. · `jstoolchains/src/components/sidebar/sidebar.tsx`
- [Navbar](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/components/navbar/navbar.tsx): feature · Top-level actions and task creation entry points. · `jstoolchains/src/components/navbar/navbar.tsx`
- [Modals](https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/components/modals): feature set · Create, edit, delete, profile, settings, and auth-related dialogs. · `jstoolchains/src/components/modals`
- [UI kit](https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/components/ui): shared components · Reusable presentation controls, pickers, toasts, and virtualization. · `jstoolchains/src/components/ui`
- [UI state](https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/contexts): contexts · Global modal and user state shared across the React tree. · `jstoolchains/src/contexts`
- [List state](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/src/reducers/listsReducer.ts): reducer · Reducer-driven list mutations and ordering updates. · `jstoolchains/src/reducers/listsReducer.ts`

### Backend

Django project, domain app, templates, and persistence.

- [Django project](https://github.com/juandarr/todo-react-django/tree/main/todo_react_django): project · Backend project configuration and site-level URL dispatch. · `todo_react_django`
- [Domain app](https://github.com/juandarr/todo-react-django/tree/main/todo): django app · Core todo/list domain models, views, serializers, forms, and signals. · `todo`
- [Models](https://github.com/juandarr/todo-react-django/blob/main/todo/models.py): orm · Lists, todos, settings, and inbox-related persistence schema. · `todo/models.py`
- [API layer](https://github.com/juandarr/todo-react-django/blob/main/todo/serializers.py): rest · Serializer and view boundary exposing the backend data surface. · `todo/serializers.py`
- [Routing](https://github.com/juandarr/todo-react-django/blob/main/todo/urls.py): urls · Backend route definitions for app and API endpoints. · `todo/urls.py`
- **SQL database**: storage · Persistent backing store accessed through Django ORM.

### Shared

Cross-cutting contracts and delivery shell.

- [Client data](https://github.com/juandarr/todo-react-django/tree/main/jstoolchains/src/lib): api/client · Typed API access, domain types, and client-side settings helpers. · `jstoolchains/src/lib`
- [Auth pages](https://github.com/juandarr/todo-react-django/tree/main/templates/registration): templates · Server-rendered login, signup, and password-management pages. · `templates/registration`
- [Shell templates](https://github.com/juandarr/todo-react-django/blob/main/templates/base.html): templates · Base HTML shell that hosts the React app and server-rendered messages. · `templates/base.html`
- [Build pipeline](https://github.com/juandarr/todo-react-django/blob/main/jstoolchains/webpack.config.js): tooling · Webpack, Tailwind, Babel, and OpenAPI generation for the frontend bundle. · `jstoolchains/webpack.config.js`
- [Schema contract](https://github.com/juandarr/todo-react-django/blob/main/schema.yml): openapi · API schema used to generate typed frontend client behavior. · `schema.yml`

### Other components

- **Browser**: client · User-facing app entry and interaction surface.

## Connections

- Browser → Shell templates: loads · Browser receives the Django-rendered shell and mounts the frontend.
- Shell templates → App shell: mounts · Base page provides the React mounting target.
- App shell → Main app: renders · React entry composes the main application tree.
- Main app → Task view: shows · Primary workspace is the task management view.
- Main app → Sidebar: includes · Main app includes list navigation.
- Main app → Navbar: includes · Main app includes top-level actions.
- Main app → Modals: opens · Application-level modal flows are coordinated from the root UI.
- Task view → UI kit: uses · Task interactions are built from shared controls.
- Sidebar → UI kit: uses · Sidebar relies on reusable UI primitives and drag/drop-friendly controls.
- Modals → UI kit: uses · Dialogs are assembled from shared UI primitives.
- Main app → UI state: shares state · Global user and modal state is injected across the tree.
- Main app → List state: updates · List mutations are coordinated through reducer state.
- Task view → Client data: fetches · Task UI consumes typed API calls and domain types.
- Sidebar → Client data: fetches · Sidebar list data is loaded through the typed client.
- Modals → Client data: mutates · Create/edit/delete/profile dialogs persist changes through the client.
- Client data → Schema contract: follows · Frontend contract is driven by the OpenAPI schema.
- Schema contract → API layer: describes · Schema documents the backend REST surface.
- Django project → Domain app: hosts · Project configuration routes requests into the domain app.
- Domain app → Models: persists · Domain behavior is centered on Django ORM models.
- Domain app → API layer: exposes · Serializers and views expose data to the frontend.
- Domain app → Routing: routes · Domain app defines its endpoint wiring.
- Models → SQL database: stores · ORM state is saved in the SQL database.
- Routing → Auth pages: serves · URL configuration includes authentication and password pages.
- Shell templates → Build pipeline: packages · Static delivery depends on the frontend build toolchain.
- Build pipeline → App shell: builds · Webpack/Tailwind pipeline produces the React assets.
