# shadowxbyte/taskflow architecture

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

- Interactive diagram: https://gitdiagram.com/shadowxbyte/taskflow
- Repository: https://github.com/shadowxbyte/taskflow

## Overview

##### What this project is (type + purpose)
**TASKFLOW** is a **full-stack Next.js application (App Router)** that ships both:
- a **server-rendered React UI** (calendar/task workspace)
- a set of **API route handlers** (auth, register, CRUD tasks)

It’s **account-based**: users authenticate (NextAuth Credentials provider) and all task operations are **scoped to the authenticated user**. Persistence is via **Prisma ORM** to **Neon Postgres**.

- Browser/UI routes
- Server route handlers (API)
- Auth/session layer
- Database access layer (Prisma)
- Postgres (Neon)

##### UI / App Router pages
- `app/layout.tsx` – root layout shell (global structure)
- `app/page.tsx` – likely landing/login entry
- `app/workspace/page.tsx` – main authenticated task/calendar workspace
- `app/providers.tsx` – React/Next providers (often SessionProvider / theme, etc.)
- `app/globals.css` + Tailwind pipeline (implied by configs)

##### API routes (server endpoints inside Next.js)
- `app/api/auth/[...nextauth]/route.ts` – NextAuth endpoint (session, callbacks)
- `app/api/register/route.ts` – user registration endpoint
- `app/api/tasks/route.ts` – tasks collection (GET list, POST create)
- `app/api/tasks/[id]/route.ts` – task item (PATCH/DELETE/GET by id depending on implementation)

##### Shared server libraries
- `lib/auth.ts` – auth utilities, NextAuth config helpers, session retrieval, etc.
- `lib/prisma.ts` – Prisma client singleton / DB connector

##### Data layer
- `prisma/schema.prisma` – data model (User, Task, etc. inferred)
- DB: Neon Postgres (external managed service)

##### Types / augmentation
- `types/next-auth.d.ts` – NextAuth session/user typing augmentations

##### Build/config
- `next.config.ts`, `tsconfig.json`, `eslint.config.mjs`, `postcss.config.mjs`, `package.json`

##### What the README adds (key runtime relationships)
From README:
- Auth: **NextAuth Credentials provider** (email/password)
- DB: **Neon PostgreSQL**
- ORM: **Prisma**
- UI: Tailwind + responsive calendar view
- Data isolation: “Each authenticated account can only access its own tasks”

- “Unauthenticated” flows (register, sign in)
- “Authenticated” flows (tasks CRUD)
- Authorization check occurs server-side (session -> userId -> DB query filter)

##### Client/UI (React components rendered via App Router)
- Routes: `/`, `/workspace`
- Uses `fetch()` to call `/api/...`
- Displays calendar + tasks

##### Next.js Server Runtime
- Hosts **Route Handlers**:
- `/api/auth/[...nextauth]` (NextAuth)
- `/api/register`
- `/api/tasks`
- `/api/tasks/:id`
- Hosts **RSC/SSR rendering** for pages (if applicable)
- Enforces auth on protected routes (commonly via session checks in handlers/pages)

##### Auth subsystem (NextAuth Credentials)
- Credential verification (email/password)
- Session issuance (cookie/JWT depending on config)
- Session retrieval used by task routes

##### Data Access Layer
- `lib/prisma.ts` Prisma Client
- `schema.prisma` models

##### Database
- Neon Postgres

- UI → `/api/register` (create user)
- UI → `/api/auth/...` (login, session)
- UI → `/api/tasks*` (CRUD)
- Task route handlers → Auth session retrieval → userId
- Task route handlers → Prisma → Postgres
- NextAuth route → Prisma → Postgres (to validate user credentials / load user)

**Key detail to annotate:** *All task queries are filtered by authenticated `userId`* (data isolation).

##### Important architectural patterns/principles to highlight

- **“Next.js integrated full-stack”**: UI + API in one deployment artifact.
- **“Route Handlers as API layer”**: `/app/api/**/route.ts`.
- **“Central auth/session boundary”**: NextAuth endpoint issues session; all task endpoints require it.
- **“Data isolation by design”**: all task reads/writes scoped by `userId` (authorization at the server).
- **“ORM gateway”**: Prisma is the only path from server code to Postgres.
- **“External managed DB”**: Neon is outside the app’s trust boundary (network connection via env vars).

##### What to label

**UI**
- `app/page.tsx` → “Landing / Auth entry”
- `app/workspace/page.tsx` → “Workspace (calendar + tasks)”
- `app/providers.tsx` → “Session/React Providers”

**API**
- `app/api/auth/[...nextauth]/route.ts` → “NextAuth (Credentials)”
- `app/api/register/route.ts` → “Register User”
- `app/api/tasks/route.ts` → “Tasks collection”
- `app/api/tasks/[id]/route.ts` → “Task item”

**Lib**
- `lib/auth.ts` → “Auth config + session helpers”
- `lib/prisma.ts` → “Prisma Client”

**DB**
- `prisma/schema.prisma` → “User/Task schema”
- “Neon Postgres”

- “POST /api/register (email,password)”
- “POST /api/auth/callback/credentials”
- “GET /api/tasks (cookie session)”
- “PATCH /api/tasks/:id (status=complete)”
- “Prisma query: Task.findMany(where userId=…)”

##### Trust boundaries / security notes
- “Browser (untrusted)”
- “Next.js Server (trusted code)”
- “External DB (managed service)”

Annotate:
- “Auth required” on `/api/tasks*` and `/workspace` (if enforced)
- “User-scoped authorization” at task handlers

For “best and most accurate”, produce:
##### Container (L2): UI vs API vs Auth vs Prisma vs DB
3. **Backend component (L3)**: per-route handler flows + auth/session check + prisma access patterns

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% L1 — Context (High-level)
    %% =========================
    subgraph L1["L1 Context — System Boundary & External Dependencies"]
        direction TB

        U["User (Browser)"]:::external

        subgraph NX1["TASKFLOW (Next.js App Router — single deployable)"]
            direction TB
            NX1_UI["Server-rendered React UI"]:::ui
            NX1_API["Route Handlers API (/app/api/..)"]:::api
            NX1_AUTH["Auth & Session (NextAuth Credentials)"]:::auth
            NX1_DAL["Data Access (Prisma ORM)"]:::data
        end

        DB1[("Neon Postgres (Managed DB)")]:::db
    end

    U -->|"HTTPS:load_pages"| NX1_UI
    U -->|"HTTPS:fetch_/api/*"| NX1_API
    NX1_API -->|"uses"| NX1_AUTH
    NX1_UI -->|"reads_session"| NX1_AUTH
    NX1_API -->|"Prisma_queries"| NX1_DAL
    NX1_AUTH -->|"user_lookup"| NX1_DAL
    NX1_DAL -->|"SQL_over_TLS"| DB1

    %% =========================
    %% L2 — Containers (Runtime)
    %% =========================
    subgraph L2["L2 Container — Runtime View (Vertical Slice)"]
        direction TB

        subgraph TRUST_BROWSER["Untrusted: Browser"]
            direction TB
            B_UI["UI Runtime (Browser)"]:::ui
        end

        subgraph TRUST_SERVER["Trusted: Next.js Server Runtime"]
            direction TB

            subgraph UI2["Web UI (App Router Pages)"]
                direction TB
                LAYOUT["Root Layout Shell (app/layout.tsx)"]:::ui
                PROVIDERS["React/Next Providers (Session/Context)"]:::ui
                GLOBALCSS["Global Styles (Tailwind/CSS)"]:::ui
                PAGE_HOME["Route: / (Landing / Auth entry)"]:::ui
                PAGE_WS["Route: /workspace (Calendar + Tasks)"]:::ui
            end

            subgraph API2["API Layer (Next.js Route Handlers)"]
                direction TB
                API_AUTH["/api/auth/[...nextauth] (NextAuth Credentials)"]:::auth
                API_REGISTER["/api/register (Register User)"]:::api
                API_TASKS["/api/tasks (Tasks collection: GET/POST)"]:::api
                API_TASK_ID["/api/tasks/:id (Task item: GET/PATCH/DELETE)"]:::api
            end

            subgraph SHARED2["Server-side Shared Libraries"]
                direction TB
                LIB_AUTH["Auth config + session helpers (lib/auth.ts)"]:::auth
                LIB_PRISMA["Prisma Client singleton (lib/prisma.ts)"]:::data
                PRISMA_SCHEMA["Prisma schema (User/Task models)"]:::data
            end

            NOTE_SCOPE["Note: Task operations are authorized & filtered by session.user.id (userId-scope)"]:::note
        end

        subgraph TRUST_DB["External: Managed Service"]
            direction TB
            DB2[("Neon Postgres")]:::db
        end
    end

    %% L2 flows (UI -> API)
    B_UI -->|"GET:/ (SSR/RSC)"| PAGE_HOME
    B_UI -->|"GET:/workspace (Auth_required)"| PAGE_WS

    B_UI -->|"POST_/api/register (email,password)"| API_REGISTER
    B_UI -->|"POST_/api/auth/callback/credentials"| API_AUTH
    B_UI -->|"GET_/api/auth/session (cookie)"| API_AUTH

    B_UI -->|"GET_/api/tasks (cookie_session)"| API_TASKS
    B_UI -->|"POST_/api/tasks (task_payload)"| API_TASKS
    B_UI -->|"GET_/api/tasks/:id"| API_TASK_ID
    B_UI -->|"PATCH_/api/tasks/:id"| API_TASK_ID
    B_UI -->|"DELETE_/api/tasks/:id"| API_TASK_ID

    %% L2 internal deps
    LAYOUT -->|"wraps"| PROVIDERS
    LAYOUT -->|"includes"| GLOBALCSS
    PAGE_HOME -->|"uses"| PROVIDERS
    PAGE_WS -->|"uses"| PROVIDERS

    API_AUTH -->|"uses"| LIB_AUTH
    API_AUTH -->|"db_access"| LIB_PRISMA

    API_REGISTER -->|"create_user"| LIB_PRISMA
    API_TASKS -->|"getSession() / authz"| LIB_AUTH
    API_TASK_ID -->|"getSession() / authz"| LIB_AUTH

    API_TASKS -->|"Prisma:Task.findMany(where userId=session.user.id)"| LIB_PRISMA
    API_TASKS -->|"Prisma:Task.create(data userId=session.user.id)"| LIB_PRISMA
    API_TASK_ID -->|"Prisma:Task.update/delete(where id AND userId=session.user.id)"| LIB_PRISMA

    LIB_PRISMA -->|"uses_models"| PRISMA_SCHEMA
    LIB_PRISMA -->|"connects"| DB2
    NOTE_SCOPE -.-> API_TASKS
    NOTE_SCOPE -.-> API_TASK_ID
    NOTE_SCOPE -.-> PAGE_WS

    %% =========================
    %% L3 — Backend Components
    %% =========================
    subgraph L3["L3 Backend Component — Route Handlers, Auth Boundary, Data Isolation"]
        direction TB

        subgraph ROUTES3["Route Handlers (/app/api/**/route.ts)"]
            direction TB
            R_AUTH["NextAuth Route Handler\n/api/auth/[...nextauth]"]:::auth
            R_REG["Register Route Handler\n/api/register"]:::api
            R_TASKS["Tasks Collection Handler\n/api/tasks"]:::api
            R_TASKID["Task Item Handler\n/api/tasks/:id"]:::api
        end

        subgraph AUTH3["Auth/Session Subsystem"]
            direction TB
            A_CFG["NextAuth config (Credentials provider)\ncallbacks/session shaping"]:::auth
            A_SESSION["Session retrieval (cookie/JWT)\n→ session.user.id"]:::auth
        end

        subgraph DAL3["Data Access Layer"]
            direction TB
            P_CLIENT["Prisma Client (singleton)"]:::data
            P_MODELS["Models: User, Task (FK: Task.userId → User.id)"]:::data
        end

        DB3[("Neon Postgres")]:::db

        ISO["Enforcement: Only allow Task rows where task.userId == session.user.id"]:::note
    end

    %% L3 auth flow
    R_AUTH -->|"loads_config"| A_CFG
    R_AUTH -->|"verify_credentials (email/password)"| P_CLIENT
    P_CLIENT -->|"SELECT_user_by_email"| DB3
    R_AUTH -->|"issues_session_cookie/JWT"| A_SESSION

    %% L3 register flow
    R_REG -->|"validate_input"| R_REG
    R_REG -->|"create_user"| P_CLIENT
    P_CLIENT -->|"INSERT_User"| DB3

    %% L3 tasks collection flow
    R_TASKS -->|"requires_auth"| A_SESSION
    A_SESSION -->|"returns_userId"| R_TASKS
    R_TASKS -->|"GET:Task.findMany(where userId)"| P_CLIENT
    R_TASKS -->|"POST:Task.create(with userId)"| P_CLIENT
    P_CLIENT -->|"SELECT/INSERT_Task"| DB3

    %% L3 tasks item flow
    R_TASKID -->|"requires_auth"| A_SESSION
    A_SESSION -->|"returns_userId"| R_TASKID
    R_TASKID -->|"GET/PATCH/DELETE with (id AND userId)"| P_CLIENT
    P_CLIENT -->|"SELECT/UPDATE/DELETE_Task"| DB3

    P_CLIENT -->|"uses"| P_MODELS
    ISO -.-> R_TASKS
    ISO -.-> R_TASKID

    %% =========================
    %% Click Events (from mapping)
    %% =========================
    click LAYOUT "https://github.com/shadowxbyte/taskflow/blob/main/app/layout.tsx"
    click GLOBALCSS "https://github.com/shadowxbyte/taskflow/blob/main/app/globals.css"
    click PAGE_HOME "https://github.com/shadowxbyte/taskflow/blob/main/app/page.tsx"
    click PAGE_WS "https://github.com/shadowxbyte/taskflow/blob/main/app/workspace/page.tsx"
    click PROVIDERS "https://github.com/shadowxbyte/taskflow/blob/main/app/providers.tsx"

    click API_AUTH "https://github.com/shadowxbyte/taskflow/blob/main/app/api/auth/[...nextauth]/route.ts"
    click API_REGISTER "https://github.com/shadowxbyte/taskflow/blob/main/app/api/register/route.ts"
    click API_TASKS "https://github.com/shadowxbyte/taskflow/blob/main/app/api/tasks/route.ts"
    click API_TASK_ID "https://github.com/shadowxbyte/taskflow/blob/main/app/api/tasks/[id]/route.ts"

    click LIB_AUTH "https://github.com/shadowxbyte/taskflow/blob/main/lib/auth.ts"
    click LIB_PRISMA "https://github.com/shadowxbyte/taskflow/blob/main/lib/prisma.ts"
    click PRISMA_SCHEMA "https://github.com/shadowxbyte/taskflow/blob/main/prisma/schema.prisma"

    %% Type augmentation (build-time)
    TYPENODE["NextAuth Type Augmentation (build-time)\ntypes/next-auth.d.ts"]:::types
    click TYPENODE "https://github.com/shadowxbyte/taskflow/blob/main/types/next-auth.d.ts"
    TYPENODE -.->|"augments_types"| NX1_AUTH
    TYPENODE -.->|"augments_session_user_id"| LIB_AUTH

    %% =========================
    %% Styles (Color coding)
    %% =========================
    classDef ui fill:#d6ebff,stroke:#1d4ed8,stroke-width:1.5px,color:#0b1f4b
    classDef api fill:#d1fae5,stroke:#047857,stroke-width:1.5px,color:#052e2b
    classDef auth fill:#efe3ff,stroke:#6d28d9,stroke-width:1.5px,color:#2e1065
    classDef data fill:#ffedd5,stroke:#c2410c,stroke-width:1.5px,color:#431407
    classDef db fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
    classDef external fill:#f3f4f6,stroke:#111827,stroke-width:1.5px,color:#111827
    classDef note fill:#fff7ed,stroke:#9a3412,stroke-width:1px,color:#7c2d12,stroke-dasharray: 5 4
    classDef types fill:#fef9c3,stroke:#a16207,stroke-width:1.2px,color:#713f12,stroke-dasharray: 4 3
```
