# esteban-m/open-task architecture

> Architecture diagram of the GitHub repository esteban-m/open-task, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/esteban-m/open-task
- Repository: https://github.com/esteban-m/open-task

## Overview

1. **Top-level shape**
   - This repo is a two-tier monorepo: a **NestJS backend** in `backend/` and a **Nuxt 3 frontend** in `frontend/`.
   - `docker-compose.yml` ties them together with **PostgreSQL** for local/dev runtime, and GitHub Actions covers CI plus CodeQL scanning.

2. **Backend as the system of record**
   - The backend owns all business rules and persistence.
   - Core domains are split into `auth`, `lists`, `tasks`, and `users`, with shared cross-cutting logic under `common/`.
   - Prisma is the persistence layer, with schema and versioned migrations in `backend/prisma/`.

3. **HTTP API boundary**
   - Client interaction goes through Nest controllers: `auth.controller.ts`, `lists.controller.ts`, `tasks.controller.ts`, and `health.controller.ts`.
   - DTOs in each domain define request/response validation boundaries.
   - Global exception handling and filters in `common/filters/` normalize API error behavior.

4. **Authentication and session model**
   - Auth is built around **JWT access + refresh tokens**.
   - Access tokens are short-lived and used for API authorization; refresh tokens are stored in **httpOnly cookies** and rotated on refresh.
   - `auth-cookie.ts`, `refresh-token-hash.ts`, and `jwt.strategy.ts` show that the backend also hashes refresh tokens before storage and uses Passport JWT for request authentication.

5. **Authorization and list isolation**
   - Access to list data is mediated by `common/list-access/ListAccessService`.
   - This is the key security boundary: it determines whether a user is owner, invited member, viewer, editor, or admin.
   - That service is used by list/task logic to prevent cross-user and cross-list data leakage.

6. **Task and list domain model**
   - `lists` manages list lifecycle plus sharing/invitations.
   - `tasks` manages task CRUD, completion state, and task metadata such as due date and description.
   - The Prisma migrations mention list color and sharing, which indicates the data model supports both presentation metadata and collaborative permissions.

7. **Realtime synchronization**
   - `tasks.gateway.ts` is the realtime boundary using **Socket.io**.
   - The backend emits task events such as create/update/delete/completed to rooms scoped by list, so only users subscribed to that list receive updates.
   - This avoids full refetches after edits and is the main collaboration mechanism.

8. **Frontend state and API orchestration**
   - The frontend uses **Pinia** stores for `auth`, `lists`, and `tasks`.
   - Reusable composables handle API access, auth state, realtime socket connection, session initialization, and derived views like calendar or list/task enrichment.
   - `useApi.ts` and `useAccessToken.ts` indicate the frontend manages bearer-token flow plus transparent refresh handling.

9. **Frontend UI composition**
   - The UI is organized by feature: layout panels, list modals, task cards/forms, kanban and calendar views, and shared UI elements like toasts and theme picker.
   - Pages are minimal and route-driven: login, register, and the main app page.
   - Nuxt middleware protects authenticated routes, so navigation policy is enforced before the page renders.

10. **Presentation vs data boundaries**
   - The frontend owns rendering, theme selection, markdown display, and local interaction state.
   - The backend owns validation, permission checks, persistence, and event emission.
   - Shared domain meaning is kept aligned through DTO-like shapes on the backend and typed stores/composables on the frontend, rather than a separate shared package.

11. **Operational and delivery concerns**
   - The backend ships with a Dockerfile and e2e tests, including an isolation test that proves multi-user separation.
   - CI validates linting, tests, Prisma migrations, and security scanning.
   - Production behavior is hardened through environment validation, rate limiting on auth endpoints, secure cookie expectations, and Swagger disabling in production.

12. **How the data flows end to end**
   - A user signs in through the frontend, receives an access token plus refresh cookie, and the frontend stores session state in Pinia.
   - CRUD actions on lists/tasks go from Nuxt to Nest over REST, with authorization enforced by JWT and list-access checks.
   - After successful task mutations, the backend writes to PostgreSQL and pushes a Socket.io event; the frontend receives it and updates the tasks store immediately.

13. **What to highlight in an architecture diagram**
   - Show three main runtime nodes: **Nuxt client**, **Nest API**, **PostgreSQL**.
   - Overlay a separate **Socket.io realtime channel** between frontend and backend.
   - Inside the backend, group modules by domain: auth, lists, tasks, and shared access/security infrastructure.
   - On the frontend, group by route pages, layout/components, Pinia stores, and composables that bridge REST, auth, theme, and realtime.

Main entry points: [`backend/src/app.module.ts`](https://github.com/esteban-m/open-task/blob/main/backend/src/app.module.ts) (App module), [`frontend/composables`](https://github.com/esteban-m/open-task/tree/main/frontend/composables) (Composables), [`backend/src/tasks`](https://github.com/esteban-m/open-task/tree/main/backend/src/tasks) (Tasks), [`frontend/pages`](https://github.com/esteban-m/open-task/tree/main/frontend/pages) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime & infra"]
  node_compose["Compose stack<br/>orchestration<br/>[docker-compose.yml]"]
  node_postgres[("PostgreSQL<br/>database")]
  node_ci["CI / CodeQL<br/>ci-security<br/>[ci.yml]"]
end

subgraph group_backend["Nest backend"]
  node_appmodule["App module<br/>nest composition<br/>[app.module.ts]"]
  node_auth["Auth<br/>nest module"]
  node_lists["Lists<br/>nest module"]
  node_tasks["Tasks<br/>nest module"]
  node_access["List access<br/>security boundary"]
  node_commonsec["Common security<br/>shared backend"]
  node_prisma[("Prisma layer<br/>persistence<br/>[schema.prisma]")]
  node_socket(("Task socket<br/>realtime gateway<br/>[tasks.gateway.ts]"))
  node_health["Health check<br/>http endpoint"]
end

subgraph group_frontend["Nuxt frontend"]
  node_pages["Pages<br/>nuxt routes"]
  node_layout["Layout UI<br/>vue components"]
  node_featureui["Feature UI<br/>vue components"]
  node_stores["Pinia stores<br/>client state"]
  node_composables["Composables<br/>client orchestration"]
  node_middleware["Route guard<br/>nuxt middleware<br/>[auth.ts]"]
  node_plugins["Client plugins<br/>nuxt plugins"]
end

node_compose -->|"runs with"| node_postgres
node_compose -->|"starts backend"| node_appmodule
node_compose -->|"starts frontend"| node_pages
node_ci -->|"tests backend"| node_appmodule
node_ci -->|"tests frontend"| node_pages
node_appmodule -->|"wires"| node_auth
node_appmodule -->|"wires"| node_lists
node_appmodule -->|"wires"| node_tasks
node_appmodule -->|"wires"| node_commonsec
node_appmodule -->|"wires"| node_prisma
node_lists -->|"checks permissions"| node_access
node_tasks -->|"checks permissions"| node_access
node_auth -->|"uses"| node_commonsec
node_auth -->|"stores tokens"| node_prisma
node_lists -->|"persists lists"| node_prisma
node_tasks -->|"persists tasks"| node_prisma
node_tasks -->|"emits events"| node_socket
node_pages -->|"protected by"| node_middleware
node_pages -->|"renders with"| node_layout
node_pages -->|"uses"| node_featureui
node_layout -->|"reads state"| node_stores
node_featureui -->|"binds state"| node_stores
node_stores -->|"orchestrated by"| node_composables
node_composables -->|"calls API"| node_auth
node_composables -->|"calls API"| node_lists
node_composables -->|"calls API"| node_tasks
node_composables -->|"subscribes"| node_socket
node_plugins -->|"bootstraps"| node_composables
node_health -.->|"reports status"| node_commonsec

click node_compose "https://github.com/esteban-m/open-task/blob/main/docker-compose.yml"
click node_ci "https://github.com/esteban-m/open-task/blob/main/.github/workflows/ci.yml"
click node_appmodule "https://github.com/esteban-m/open-task/blob/main/backend/src/app.module.ts"
click node_auth "https://github.com/esteban-m/open-task/tree/main/backend/src/auth"
click node_lists "https://github.com/esteban-m/open-task/tree/main/backend/src/lists"
click node_tasks "https://github.com/esteban-m/open-task/tree/main/backend/src/tasks"
click node_access "https://github.com/esteban-m/open-task/blob/main/backend/src/common/list-access/list-access.service.ts"
click node_commonsec "https://github.com/esteban-m/open-task/tree/main/backend/src/common"
click node_prisma "https://github.com/esteban-m/open-task/blob/main/backend/prisma/schema.prisma"
click node_socket "https://github.com/esteban-m/open-task/blob/main/backend/src/tasks/tasks.gateway.ts"
click node_health "https://github.com/esteban-m/open-task/blob/main/backend/src/health.controller.ts"
click node_pages "https://github.com/esteban-m/open-task/tree/main/frontend/pages"
click node_layout "https://github.com/esteban-m/open-task/tree/main/frontend/components/layout"
click node_featureui "https://github.com/esteban-m/open-task/tree/main/frontend/components"
click node_stores "https://github.com/esteban-m/open-task/tree/main/frontend/stores"
click node_composables "https://github.com/esteban-m/open-task/tree/main/frontend/composables"
click node_middleware "https://github.com/esteban-m/open-task/blob/main/frontend/middleware/auth.ts"
click node_plugins "https://github.com/esteban-m/open-task/tree/main/frontend/plugins"

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_compose,node_postgres,node_ci toneBlue
class node_appmodule,node_auth,node_lists,node_tasks,node_access,node_commonsec,node_prisma,node_socket,node_health toneAmber
class node_pages,node_layout,node_featureui,node_stores,node_composables,node_middleware,node_plugins toneMint
```

## Components

### Runtime & infra

Local execution, database, and deployment/CI concerns.

- [Compose stack](https://github.com/esteban-m/open-task/blob/main/docker-compose.yml): orchestration · Local runtime wiring for backend, frontend, and PostgreSQL. · `docker-compose.yml`
- **PostgreSQL**: database · Primary persistence store for lists, tasks, users, and sharing state.
- [CI / CodeQL](https://github.com/esteban-m/open-task/blob/main/.github/workflows/ci.yml): ci-security · GitHub Actions pipelines for tests, linting, migrations, and security scanning. · `.github/workflows/ci.yml`

### Nest backend

HTTP API, domain services, persistence, and realtime events.

- [App module](https://github.com/esteban-m/open-task/blob/main/backend/src/app.module.ts): nest composition · Backend composition root that wires modules, guards, filters, and providers. · `backend/src/app.module.ts`
- [Auth](https://github.com/esteban-m/open-task/tree/main/backend/src/auth): nest module · JWT login, refresh flow, cookie handling, and request authentication. · `backend/src/auth`
- [Lists](https://github.com/esteban-m/open-task/tree/main/backend/src/lists): nest module · List lifecycle, sharing, invitations, and ownership/member workflows. · `backend/src/lists`
- [Tasks](https://github.com/esteban-m/open-task/tree/main/backend/src/tasks): nest module · Task CRUD, completion, metadata updates, and realtime emission. · `backend/src/tasks`
- [List access](https://github.com/esteban-m/open-task/blob/main/backend/src/common/list-access/list-access.service.ts): security boundary · Permission resolution for owner, invited member, viewer, editor, and admin access. · `backend/src/common/list-access/list-access.service.ts`
- [Common security](https://github.com/esteban-m/open-task/tree/main/backend/src/common): shared backend · Global filters, JWT guard/strategy, production secret validation, and request helpers. · `backend/src/common`
- [Prisma layer](https://github.com/esteban-m/open-task/blob/main/backend/prisma/schema.prisma): persistence · Schema, migrations, and database access services for the backend. · `backend/prisma/schema.prisma`
- [Task socket](https://github.com/esteban-m/open-task/blob/main/backend/src/tasks/tasks.gateway.ts): realtime gateway · Socket.io channel that broadcasts list-scoped task events. · `backend/src/tasks/tasks.gateway.ts`
- [Health check](https://github.com/esteban-m/open-task/blob/main/backend/src/health.controller.ts): http endpoint · Lightweight operational endpoint for service readiness/liveness. · `backend/src/health.controller.ts`

### Nuxt frontend

Route pages, UI composition, state, and client-side orchestration.

- [Pages](https://github.com/esteban-m/open-task/tree/main/frontend/pages): nuxt routes · Minimal route entrypoints for login, registration, and the main app. · `frontend/pages`
- [Layout UI](https://github.com/esteban-m/open-task/tree/main/frontend/components/layout): vue components · App shell, sidebars, modals, toasts, and shared presentation elements. · `frontend/components/layout`
- [Feature UI](https://github.com/esteban-m/open-task/tree/main/frontend/components): vue components · Calendar, kanban, list sharing/editing, task cards, and task forms. · `frontend/components`
- [Pinia stores](https://github.com/esteban-m/open-task/tree/main/frontend/stores): client state · Auth, lists, and tasks state containers coordinating API and UI updates. · `frontend/stores`
- [Composables](https://github.com/esteban-m/open-task/tree/main/frontend/composables): client orchestration · API access, access tokens, realtime sync, session init, theming, and derived views. · `frontend/composables`
- [Route guard](https://github.com/esteban-m/open-task/blob/main/frontend/middleware/auth.ts): nuxt middleware · Protects authenticated routes before page render. · `frontend/middleware/auth.ts`
- [Client plugins](https://github.com/esteban-m/open-task/tree/main/frontend/plugins): nuxt plugins · Bootstraps auth, realtime, and theme behavior on the client. · `frontend/plugins`

## Connections

- Compose stack → PostgreSQL: runs with · Local services share the PostgreSQL instance.
- Compose stack → App module: starts backend · Docker compose launches the Nest API service.
- Compose stack → Pages: starts frontend · Docker compose launches the Nuxt client service.
- CI / CodeQL → App module: tests backend · CI validates backend linting, tests, and Prisma checks.
- CI / CodeQL → Pages: tests frontend · CI validates frontend build/lint coverage.
- App module → Auth: wires · App root imports authentication module.
- App module → Lists: wires · App root imports list domain module.
- App module → Tasks: wires · App root imports task domain module.
- App module → Common security: wires · App root applies shared security concerns.
- App module → Prisma layer: wires · App root connects persistence services.
- Lists → List access: checks permissions · List operations validate membership and roles through the access service.
- Tasks → List access: checks permissions · Task operations are scoped by list access rules.
- Auth → Common security: uses · JWT guard/strategy, cookies, and exception handling support auth flow.
- Auth → Prisma layer: stores tokens · Refresh token hashes and user data persist through Prisma.
- Lists → Prisma layer: persists lists · List metadata, invitations, and sharing state are stored in PostgreSQL.
- Tasks → Prisma layer: persists tasks · Task CRUD and completion state are stored in PostgreSQL.
- Tasks → Task socket: emits events · Task mutations broadcast list-scoped realtime updates.
- Pages → Route guard: protected by · Authenticated routes are gated before render.
- Pages → Layout UI: renders with · Pages assemble the shared application shell.
- Pages → Feature UI: uses · Route views compose feature components.
- Layout UI → Pinia stores: reads state · Navigation and shell UI depend on central client state.
- Feature UI → Pinia stores: binds state · Feature widgets read and write Pinia state.
- Pinia stores → Composables: orchestrated by · Stores rely on composables for API, sessions, and realtime integration.
- Composables → Auth: calls API · Auth composables exchange credentials and refresh session state.
- Composables → Lists: calls API · List composables fetch and mutate list data.
- Composables → Tasks: calls API · Task composables fetch and mutate task data.
- Composables → Task socket: subscribes · Realtime composables connect the client to task list rooms.
- Client plugins → Composables: bootstraps · Client plugins initialize auth, realtime, and theme infrastructure.
- Health check → Common security: reports status · Operational endpoint sits alongside shared backend concerns.
