# martynasmatdev/labelflow architecture

> Architecture diagram of the GitHub repository martynasmatdev/labelflow, 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/martynasmatdev/labelflow
- Repository: https://github.com/martynasmatdev/labelflow

## Overview

LabelFlow is a single Django monolith with server-rendered pages. The backend, routing, templates, static assets, and persistence all live in one repository. The app uses SQLite by default and stores user-uploaded files separately under `media/`, while CSS/JS live in `static/`.

The Django project config is in `labelflow/` (`settings.py`, `urls.py`, `asgi.py`, `wsgi.py`). `manage.py` is the entry point for migrations, tests, admin setup, and local server startup.

The application is split into three main domain apps under `apps/`, which form the core architectural boundaries:
- `accounts` for authentication and user profile management
- `projects` for project and team organization
- `images` for image upload, listing, and annotation workflows

`accounts` owns registration/login/profile flows. The presence of `forms.py`, `views.py`, `urls.py`, and an `admin.py` suggests it handles Django auth-driven screens plus profile editing, with templates for login/register/profile in the shared `templates/` tree.

`projects` is the collaboration layer. Its migrations show project lifecycle changes, including an archived-state field, so this app likely manages project creation, project detail views, lists, archived projects, and team membership/management.

`images` is the labeling/annotation layer. Its migrations indicate richer image metadata: tags, status changes, and bounding boxes. That points to a workflow where uploaded images are associated with projects and then annotated or categorized.

The main data flow is request-driven and page-based:
1. Browser requests hit `labelflow/urls.py`.
2. URLs dispatch into one of the three apps.
3. Views read/write Django models via SQLite.
4. Templates render HTML responses.
5. Static JS/CSS provide client-side behavior on interactive pages like image annotation.

The templates are organized by concern. `templates/base.html` and `templates/app/app_base.html` provide shared layout, while `templates/app/` contains feature pages such as dashboard, project list/detail/create, image list/detail/upload/annotate, team management, archived projects, and profile. `templates/registration/` contains the auth pages.

The front end is intentionally lightweight: HTML templates with a shared stylesheet and a small JavaScript bundle. This suggests the app relies primarily on Django server-side rendering, with JavaScript augmenting annotation and interaction-heavy screens rather than running a full SPA.

Django admin support is present in each app, which means the domain objects are manageable through the built-in admin interface in addition to the custom UI. That gives the system two administrative entry points: end-user pages and staff/admin CRUD.

Architecturally, the key boundaries are:
- configuration layer (`labelflow/`)
- domain apps (`accounts`, `projects`, `images`)
- presentation layer (`templates/`, `static/`)
- persistence layer (SQLite + migrations + media files)

Overall, LabelFlow is best understood as a modular Django web application for team-based image labeling, with projects as the organizing container, accounts as the identity layer, and images as the annotation workload.

Main entry points: [`labelflow/settings.py`](https://github.com/martynasmatdev/labelflow/blob/main/labelflow/settings.py) (Settings), [`apps/accounts/views.py`](https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/views.py) (Account views), [`apps/images/views.py`](https://github.com/martynasmatdev/labelflow/blob/main/apps/images/views.py) (Image views), [`labelflow/urls.py`](https://github.com/martynasmatdev/labelflow/blob/main/labelflow/urls.py) (Root URLs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_config["Configuration"]
  node_manage_py["manage.py<br/>entrypoint<br/>[manage.py]"]
  node_settings["Settings<br/>django config<br/>[settings.py]"]
  node_urls_root["Root URLs<br/>router<br/>[urls.py]"]
  node_runtime["ASGI/WSGI<br/>runtime"]
end

subgraph group_accounts["Accounts"]
  node_accounts_models[("Account data<br/>django models<br/>[models.py]")]
  node_accounts_forms["Account forms<br/>[forms.py]"]
  node_accounts_views["Account views<br/>[views.py]"]
  node_accounts_urls["Account URLs<br/>routes<br/>[urls.py]"]
end

subgraph group_projects["Projects"]
  node_projects_models[("Project data<br/>django models<br/>[models.py]")]
  node_projects_views["Project views<br/>[views.py]"]
  node_projects_urls["Project URLs<br/>routes<br/>[urls.py]"]
end

subgraph group_images["Images"]
  node_images_models[("Image data<br/>django models<br/>[models.py]")]
  node_images_views["Image views<br/>[views.py]"]
  node_images_urls["Image URLs<br/>routes<br/>[urls.py]"]
end

subgraph group_presentation["Presentation"]
  node_base_templates["Base templates<br/>[base.html]"]
  node_app_templates["App pages<br/>templates<br/>[app_base.html]"]
  node_auth_templates["Auth pages<br/>templates<br/>[login.html]"]
  node_main_css["Main CSS<br/>static stylesheet<br/>[main.css]"]
  node_main_js["Main JS<br/>static script<br/>[main.js]"]
end

subgraph group_data["Data"]
  node_sqlite_db[("SQLite DB<br/>database")]
  node_migrations["Migrations<br/>schema history<br/>[0001_initial.py]"]
end

node_manage_py -->|"loads"| node_settings
node_manage_py -->|"starts"| node_urls_root
node_runtime -->|"serves"| node_urls_root
node_settings -->|"configures"| node_sqlite_db
node_settings -->|"installs"| node_accounts_urls
node_settings -->|"installs"| node_projects_urls
node_settings -->|"installs"| node_images_urls
node_urls_root -->|"routes"| node_accounts_urls
node_urls_root -->|"routes"| node_projects_urls
node_urls_root -->|"routes"| node_images_urls
node_accounts_urls -->|"dispatches"| node_accounts_views
node_accounts_views -->|"uses"| node_accounts_forms
node_accounts_views -->|"reads/writes"| node_accounts_models
node_projects_urls -->|"dispatches"| node_projects_views
node_projects_views -->|"reads/writes"| node_projects_models
node_projects_views -->|"renders"| node_app_templates
node_images_urls -->|"dispatches"| node_images_views
node_images_views -->|"reads/writes"| node_images_models
node_images_views -->|"augments"| node_main_js
node_images_views -->|"renders"| node_app_templates
node_accounts_views -->|"renders"| node_auth_templates
node_accounts_views -->|"extends"| node_base_templates
node_projects_views -->|"styles"| node_main_css
node_images_views -->|"styles"| node_main_css
node_migrations -.->|"evolves"| node_accounts_models
node_migrations -.->|"evolves"| node_projects_models
node_migrations -.->|"evolves"| node_images_models

click node_manage_py "https://github.com/martynasmatdev/labelflow/blob/main/manage.py"
click node_settings "https://github.com/martynasmatdev/labelflow/blob/main/labelflow/settings.py"
click node_urls_root "https://github.com/martynasmatdev/labelflow/blob/main/labelflow/urls.py"
click node_accounts_models "https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/models.py"
click node_accounts_forms "https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/forms.py"
click node_accounts_views "https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/views.py"
click node_accounts_urls "https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/urls.py"
click node_projects_models "https://github.com/martynasmatdev/labelflow/blob/main/apps/projects/models.py"
click node_projects_views "https://github.com/martynasmatdev/labelflow/blob/main/apps/projects/views.py"
click node_projects_urls "https://github.com/martynasmatdev/labelflow/blob/main/apps/projects/urls.py"
click node_images_models "https://github.com/martynasmatdev/labelflow/blob/main/apps/images/models.py"
click node_images_views "https://github.com/martynasmatdev/labelflow/blob/main/apps/images/views.py"
click node_images_urls "https://github.com/martynasmatdev/labelflow/blob/main/apps/images/urls.py"
click node_base_templates "https://github.com/martynasmatdev/labelflow/blob/main/templates/base.html"
click node_app_templates "https://github.com/martynasmatdev/labelflow/blob/main/templates/app/app_base.html"
click node_auth_templates "https://github.com/martynasmatdev/labelflow/blob/main/templates/registration/login.html"
click node_main_css "https://github.com/martynasmatdev/labelflow/blob/main/static/css/main.css"
click node_main_js "https://github.com/martynasmatdev/labelflow/blob/main/static/js/main.js"
click node_migrations "https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/migrations/0001_initial.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_manage_py,node_settings,node_urls_root,node_runtime toneBlue
class node_accounts_models,node_accounts_forms,node_accounts_views,node_accounts_urls toneAmber
class node_projects_models,node_projects_views,node_projects_urls toneMint
class node_images_models,node_images_views,node_images_urls toneRose
class node_base_templates,node_app_templates,node_auth_templates,node_main_css,node_main_js toneIndigo
class node_sqlite_db,node_migrations toneTeal
```

## Components

### Configuration

Django project entrypoints and runtime config.

- [manage.py](https://github.com/martynasmatdev/labelflow/blob/main/manage.py): entrypoint · CLI entrypoint for admin tasks, migrations, tests, and local runs. · `manage.py`
- [Settings](https://github.com/martynasmatdev/labelflow/blob/main/labelflow/settings.py): django config · Project settings, including database and app wiring. · `labelflow/settings.py`
- [Root URLs](https://github.com/martynasmatdev/labelflow/blob/main/labelflow/urls.py): router · Top-level URL dispatcher for the Django site. · `labelflow/urls.py`
- **ASGI/WSGI**: runtime · Server adapters for async and WSGI deployment.

### Accounts

Authentication and profile domain.

- [Account data](https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/models.py): django models · Users, profiles, and auth-related persistence. · `apps/accounts/models.py`
- [Account forms](https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/forms.py): forms · Registration, login, and profile editing forms. · `apps/accounts/forms.py`
- [Account views](https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/views.py): views · Authentication and profile page handlers. · `apps/accounts/views.py`
- [Account URLs](https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/urls.py): routes · URL patterns for auth and profile flows. · `apps/accounts/urls.py`

### Projects

Project and team collaboration domain.

- [Project data](https://github.com/martynasmatdev/labelflow/blob/main/apps/projects/models.py): django models · Projects, archived state, and team membership data. · `apps/projects/models.py`
- [Project views](https://github.com/martynasmatdev/labelflow/blob/main/apps/projects/views.py): views · Project list, detail, create, archive, and team screens. · `apps/projects/views.py`
- [Project URLs](https://github.com/martynasmatdev/labelflow/blob/main/apps/projects/urls.py): routes · URL patterns for project and team management pages. · `apps/projects/urls.py`

### Images

Upload and annotation domain.

- [Image data](https://github.com/martynasmatdev/labelflow/blob/main/apps/images/models.py): django models · Uploaded images, tags, statuses, and bounding boxes. · `apps/images/models.py`
- [Image views](https://github.com/martynasmatdev/labelflow/blob/main/apps/images/views.py): views · Upload, list, detail, and annotation handlers. · `apps/images/views.py`
- [Image URLs](https://github.com/martynasmatdev/labelflow/blob/main/apps/images/urls.py): routes · URL patterns for labeling workflow pages. · `apps/images/urls.py`

### Presentation

Server-rendered templates and static assets.

- [Base templates](https://github.com/martynasmatdev/labelflow/blob/main/templates/base.html): templates · Shared HTML shell for the site and app area. · `templates/base.html`
- [App pages](https://github.com/martynasmatdev/labelflow/blob/main/templates/app/app_base.html): templates · Server-rendered pages for dashboard, projects, images, team, and profile. · `templates/app/app_base.html`
- [Auth pages](https://github.com/martynasmatdev/labelflow/blob/main/templates/registration/login.html): templates · Login and registration screens. · `templates/registration/login.html`
- [Main CSS](https://github.com/martynasmatdev/labelflow/blob/main/static/css/main.css): static stylesheet · Shared styling for the server-rendered UI. · `static/css/main.css`
- [Main JS](https://github.com/martynasmatdev/labelflow/blob/main/static/js/main.js): static script · Client-side behavior for interactive pages such as annotation. · `static/js/main.js`

### Data

Persistence and schema evolution.

- **SQLite DB**: database · Default local persistence backend configured by Django settings.
- [Migrations](https://github.com/martynasmatdev/labelflow/blob/main/apps/accounts/migrations/0001_initial.py): schema history · Schema evolution for accounts, projects, and images. · `apps/accounts/migrations/0001_initial.py`

## Connections

- manage.py → Settings: loads · Management commands resolve project configuration.
- manage.py → Root URLs: starts · Runs the site or administrative workflows through the project entrypoints.
- ASGI/WSGI → Root URLs: serves · ASGI/WSGI adapters hand requests to the URL router.
- Settings → SQLite DB: configures · Settings define the default SQLite persistence backend.
- Settings → Account URLs: installs · Project settings include the domain apps.
- Settings → Project URLs: installs · Project settings include the domain apps.
- Settings → Image URLs: installs · Project settings include the domain apps.
- Root URLs → Account URLs: routes · Top-level routes delegate auth paths to the accounts app.
- Root URLs → Project URLs: routes · Top-level routes delegate project paths to the projects app.
- Root URLs → Image URLs: routes · Top-level routes delegate labeling paths to the images app.
- Account URLs → Account views: dispatches · Account routes resolve to page handlers.
- Account views → Account forms: uses · Views rely on forms for registration and profile editing.
- Account views → Account data: reads/writes · Authentication and profile screens persist account data.
- Project URLs → Project views: dispatches · Project routes resolve to collaboration handlers.
- Project views → Project data: reads/writes · Project pages manage project and membership records.
- Project views → App pages: renders · Project screens are server-rendered from shared app templates.
- Image URLs → Image views: dispatches · Image routes resolve to upload and annotation handlers.
- Image views → Image data: reads/writes · Labeling workflows persist image metadata and annotations.
- Image views → Main JS: augments · Interactive annotation screens use client-side behavior.
- Image views → App pages: renders · Image workflow pages are rendered through the shared app shell.
- Account views → Auth pages: renders · Auth and profile flows use registration/login templates.
- Account views → Base templates: extends · Account pages share the global layout.
- Project views → Main CSS: styles · Project pages share the common stylesheet.
- Image views → Main CSS: styles · Annotation pages share the common stylesheet.
- Migrations → Account data: evolves · Schema history tracks account model changes.
- Migrations → Project data: evolves · Schema history tracks project model changes.
- Migrations → Image data: evolves · Schema history tracks image model changes.
