How esteban-m/open-task works
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: app.module.ts App module · composables Composables · tasks Tasks · pages Pages
Components 19
Runtime & infra
Local execution, database, and deployment/CI concerns.
- Compose stack · Local runtime wiring for backend, frontend, and PostgreSQL.
docker-compose.yml - PostgreSQL · Primary persistence store for lists, tasks, users, and sharing state.
- CI / CodeQL · 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 · Backend composition root that wires modules, guards, filters, and providers.
backend/src/app.module.ts - Auth · JWT login, refresh flow, cookie handling, and request authentication.
backend/src/auth - Lists · List lifecycle, sharing, invitations, and ownership/member workflows.
backend/src/lists - Tasks · Task CRUD, completion, metadata updates, and realtime emission.
backend/src/tasks - List access · Permission resolution for owner, invited member, viewer, editor, and admin access.
backend/src/common/list-access/list-access.service.ts - Common security · Global filters, JWT guard/strategy, production secret validation, and request helpers.
backend/src/common - Prisma layer · Schema, migrations, and database access services for the backend.
backend/prisma/schema.prisma - Task socket · Socket.io channel that broadcasts list-scoped task events.
backend/src/tasks/tasks.gateway.ts - Health check · Lightweight operational endpoint for service readiness/liveness.
backend/src/health.controller.ts
Nuxt frontend
Route pages, UI composition, state, and client-side orchestration.
- Pages · Minimal route entrypoints for login, registration, and the main app.
frontend/pages - Layout UI · App shell, sidebars, modals, toasts, and shared presentation elements.
frontend/components/layout - Feature UI · Calendar, kanban, list sharing/editing, task cards, and task forms.
frontend/components - Pinia stores · Auth, lists, and tasks state containers coordinating API and UI updates.
frontend/stores - Composables · API access, access tokens, realtime sync, session init, theming, and derived views.
frontend/composables - Route guard · Protects authenticated routes before page render.
frontend/middleware/auth.ts - Client plugins · Bootstraps auth, realtime, and theme behavior on the client.
frontend/plugins
Connections 29
- 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.