# blockly-website/blockly-student-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/blockly-website/blockly-student-tracker
- Repository: https://github.com/blockly-website/blockly-student-tracker

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **serverless, frontend-only web app** (Next.js App Router) that implements a **self-hosted student schedule + task tracker**. The key architectural constraint is explicitly stated:

- **No backend server**
- **No custom API layer**
- **Frontend talks directly to Supabase** (Auth + Postgres + RLS)

##### Client application (Next.js / React / MUI)
- `app/` (routing, layout, pages)
- `app/layout.tsx`: root layout, fonts/metadata, top-level providers
- `app/page.tsx`: **AuthGate → Dashboard** entrypoint
- `app/signin/page.tsx`: sign-in route
- `components/`: feature modules / UI shells
- `AuthGate.tsx`: session check + redirect logic
- `Dashboard.tsx`: tab shell; the “main surface” that hosts features
- Feature managers/views: `DayView`, `WeekView`, `CalendarManager`, `TaskManager`, `ScheduleManager`, `SettingsPanel`
- `SupabaseSignIn.tsx`: auth UI for sign in/up/reset
- `DemoDataButton.tsx`: seeds demo data (important data-write path)
- `DevPanel.tsx`: dev-only utilities (should be visually separated as “dev only”)
- `lib/`: cross-cutting concerns
- `lib/supabase.ts`: **Supabase JS client init** (the “data access layer”)
- `lib/preferences.tsx`: preferences context + time formatting (local state)
- `lib/types.ts`: shared types/interfaces

##### Supabase (managed backend)
- `supabase/setup.sql`: defines **4 tables + constraints + RLS + FORCE RLS**
- `schedule_types`
- `schedule_blocks`
- `schedule_overrides`
- `tasks`
- Supabase services used:
- **Auth** (email/password + optional OAuth)
- **PostgreSQL**
- **Row Level Security** policies (authorization boundary)

##### Platform / delivery (optional but accurate)
- Hosting targets (Vercel/Netlify/Cloudflare/self-host) from README
- Environment configuration (`.env.example`, `next.config.ts`)

Because there’s no custom backend, the most important things to capture are:

##### Sign-in triggers Supabase Auth
- email/password OR OAuth redirect → provider → back to Supabase → session
##### With a session, feature components execute CRUD via Supabase JS client
- Read/write schedules, tasks, overrides in **Postgres**
- All queries are constrained by **RLS** (authorization boundary)

##### Data ownership / security flow (important to show explicitly)
- **Client is untrusted** → all enforcement is in **Supabase RLS**
- anon key is used client-side → **never service role**

##### Local-only state flow
- `SettingsPanel` ↔ `PreferencesContext` ↔ **Browser storage** (implied by “saved locally”)
- This should be a separate data store node like “Local Storage / IndexedDB” (even if implementation detail isn’t shown in tree, the behavior is explicitly described).

##### Important architectural patterns/design principles to annotate
- **Backendless / BaaS architecture**: Supabase is the backend.
- **Client-side data access layer**: `lib/supabase.ts` as the single initialization point.
- **Authorization at the data layer**: RLS + FORCE RLS as the core security mechanism.
- **Feature-component modularization**: each “Manager/View” maps to a domain (tasks, schedules, overrides).

Entities:
- Student (Browser)
- Hosting (Vercel/etc.)
- Supabase (Auth + DB + RLS)
- Optional OAuth providers

Containers:
- Next.js Web App (React/MUI, PWA)
- Supabase Auth
- Supabase Postgres (4 tables)
- Local Storage (preferences)
- OAuth provider(s) (optional)

Inside “Next.js Web App”:
- Routing (App Router)
- AuthGate / SupabaseSignIn
- Dashboard
- DayView / WeekView / CalendarManager / TaskManager / ScheduleManager / SettingsPanel
- lib: supabase client + preferences context + types

##### Make data model visible (because it drives the whole app)
A “Data” section on the Supabase side listing the 4 tables and the key relationships:
- `schedule_types` → `schedule_blocks` (blocks belong to a schedule type)
- `schedule_overrides` (date-based override of schedule)
- `tasks` (optionally linked to class/schedule block/type—reflect whatever is implemented in SQL)

- `user_id` on every table
- RLS policy: `user_id = auth.uid()`

##### PWA is a delivery/runtime concern, not a backend
PWA elements to include:
- Optional note: “Offline capability” only if actually implemented; otherwise just “Installable PWA”.

##### “Don’t overthink it” but be detailed: how to split into many components safely
Given the repo is small, it’s safe to separate aggressively by:
- Separate local preferences storage as its own store

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External / Delivery
  %% =========================
  Student["Student"]:::external

  subgraph "Hosting / CDN"
    Host["Static+EdgeHosting (Vercel/Netlify/Cloudflare/self-host)"]:::platform
    PWAAssets["PWAAssets (manifest+icons)"]:::platform
  end

  subgraph "OAuth Provider(s) (Optional)"
    OAuth["Google/GitHub/etc."]:::external
  end

  %% =========================
  %% Client: Browser + Next.js (no backend)
  %% =========================
  subgraph "Browser (Next.js App Router • React • MUI • PWA)"
    NextApp["Next.jsWebApp"]:::client

    subgraph "App Router"
      Layout["RootLayout (app/layout.tsx)"]:::client
      Globals["GlobalStyles (app/globals.css)"]:::client
      RouteRoot["Route '/' (app/page.tsx)"]:::client
      RouteSignin["Route '/signin' (app/signin/page.tsx)"]:::client
    end

    Providers["AppProviders (theme/MUI/etc.)"]:::client

    subgraph "Auth & Shell"
      AuthGate["AuthGate (session check+redirect)"]:::client
      SignInUI["SupabaseSignIn (email/OAuth)"]:::client
      Dashboard["Dashboard (tab shell/feature host)"]:::client
    end

    subgraph "Feature Modules (inside Dashboard)"
      DayView["DayView (Today)"]:::client
      WeekView["WeekView (Week)"]:::client
      CalendarMgr["CalendarManager"]:::client
      TaskMgr["TaskManager"]:::client
      ScheduleMgr["ScheduleManager (Setup)"]:::client
      Settings["SettingsPanel (Preferences UI)"]:::client
      DemoSeed["DemoDataButton (bulk inserts)"]:::client
      DevPanel["DevPanel (dev-only)"]:::dev
    end

    subgraph "Client Data / State"
      SupaClient["SupabaseJSClient (lib/supabase.ts)"]:::dataaccess
      PrefCtx["PreferencesContext (lib/preferences.tsx)"]:::state
      Types["SharedTypes (lib/types.ts)"]:::state
      LocalStore[("LocalStorage/IndexedDB (preferences)")]:::localstore
    end
  end

  %% =========================
  %% Supabase (Managed backend)
  %% =========================
  subgraph "Supabase Project (BaaS Backend)"
    Supabase["Supabase"]:::supabase

    subgraph "Supabase Auth"
      Auth["Auth (email/password)"]:::supabase
      AuthOAuth["OAuth Redirect Handler"]:::supabase
    end

    subgraph "Supabase Data Plane"
      PostgREST["PostgREST / API (managed)"]:::supabase
      RLS["RLS+FORCERLS (user_id=auth.uid())"]:::security
      DB[("Postgres")]:::db

      subgraph "Tables"
        TTypes["schedule_types"]:::db
        TBlocks["schedule_blocks"]:::db
        TOverrides["schedule_overrides"]:::db
        TTasks["tasks"]:::db
      end

      Schema["Schema+Policies (setup.sql)"]:::security
    end
  end

  %% =========================
  %% Primary flows (vertical)
  %% =========================
  Student -->|"uses"| NextApp
  Host -->|"load_web_app"| NextApp
  PWAAssets -->|"installable_assets"| NextApp

  NextApp -->|"renders_with"| Layout
  Layout -->|"applies"| Globals
  Layout -->|"wraps"| Providers
  Providers -->|"routes"| RouteRoot
  Providers -->|"routes"| RouteSignin

  RouteRoot -->|"entry"| AuthGate
  AuthGate -->|"get_session"| SupaClient
  AuthGate -->|"if_authed_show"| Dashboard
  AuthGate -->|"if_not_authed_redirect"| RouteSignin
  RouteSignin -->|"render"| SignInUI

  SignInUI -->|"sign_in"| SupaClient
  SupaClient -->|"auth_request"| Auth
  SignInUI -.->|"oauth_redirect"| AuthOAuth
  AuthOAuth -.->|"provider_login"| OAuth
  OAuth -.->|"oauth_callback"| AuthOAuth
  AuthOAuth -.->|"issue_session"| Auth
  Auth -->|"session_tokens"| SupaClient

  Dashboard -->|"hosts"| DayView
  Dashboard -->|"hosts"| WeekView
  Dashboard -->|"hosts"| CalendarMgr
  Dashboard -->|"hosts"| TaskMgr
  Dashboard -->|"hosts"| ScheduleMgr
  Dashboard -->|"hosts"| Settings
  Dashboard -->|"hosts"| DemoSeed
  Dashboard -.->|"hosts_dev_only"| DevPanel

  %% CRUD paths to Supabase (no custom API)
  DayView -->|"CRUD_schedules"| SupaClient
  WeekView -->|"CRUD_schedules"| SupaClient
  CalendarMgr -->|"CRUD_schedule_types_blocks_overrides"| SupaClient
  TaskMgr -->|"CRUD_tasks"| SupaClient
  ScheduleMgr -->|"CRUD_schedule_types_blocks"| SupaClient
  DemoSeed -->|"bulk_inserts"| SupaClient

  SupaClient -->|"query_write"| PostgREST
  PostgREST -->|"enforce_RLS"| RLS
  RLS -->|"db_access"| DB

  %% Data model relationships (inside DB)
  DB --> TTypes
  DB --> TBlocks
  DB --> TOverrides
  DB --> TTasks
  TTypes -->|"owns"| TBlocks
  TOverrides -.->|"date_based_override"| TTypes

  %% Policies defined in setup.sql
  Schema -->|"defines"| RLS
  Schema -->|"creates"| DB

  %% Local-only preferences
  Settings -->|"read_write_preferences"| PrefCtx
  PrefCtx -->|"persist"| LocalStore

  %% Types used across UI/modules
  Types -.->|"shared_models"| DayView
  Types -.->|"shared_models"| WeekView
  Types -.->|"shared_models"| CalendarMgr
  Types -.->|"shared_models"| TaskMgr
  Types -.->|"shared_models"| ScheduleMgr
  Types -.->|"shared_models"| Settings

  %% Tenancy model note
  Supabase ---|"One_project_per_student (operational_tenancy)"| Supabase

  %% =========================
  %% Click events (paths only; not shown on nodes)
  %% =========================
  click Layout "https://github.com/blockly-website/blockly-student-tracker/blob/main/app/layout.tsx"
  click Globals "https://github.com/blockly-website/blockly-student-tracker/blob/main/app/globals.css"
  click RouteRoot "https://github.com/blockly-website/blockly-student-tracker/blob/main/app/page.tsx"
  click RouteSignin "https://github.com/blockly-website/blockly-student-tracker/blob/main/app/signin/page.tsx"

  click Providers "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/AppProviders.tsx"
  click AuthGate "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/AuthGate.tsx"
  click Dashboard "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/Dashboard.tsx"
  click SignInUI "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/SupabaseSignIn.tsx"

  click DayView "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/DayView.tsx"
  click WeekView "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/WeekView.tsx"
  click CalendarMgr "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/CalendarManager.tsx"
  click TaskMgr "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/TaskManager.tsx"
  click ScheduleMgr "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/ScheduleManager.tsx"
  click Settings "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/SettingsPanel.tsx"
  click DemoSeed "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/DemoDataButton.tsx"
  click DevPanel "https://github.com/blockly-website/blockly-student-tracker/blob/main/components/DevPanel.tsx"

  click SupaClient "https://github.com/blockly-website/blockly-student-tracker/blob/main/lib/supabase.ts"
  click PrefCtx "https://github.com/blockly-website/blockly-student-tracker/blob/main/lib/preferences.tsx"
  click Types "https://github.com/blockly-website/blockly-student-tracker/blob/main/lib/types.ts"

  click Schema "https://github.com/blockly-website/blockly-student-tracker/blob/main/supabase/setup.sql"

  click PWAAssets "https://github.com/blockly-website/blockly-student-tracker/blob/main/public/manifest.json"
  click PWAAssets "https://github.com/blockly-website/blockly-student-tracker/tree/main/public/icons/"
  click NextApp "https://github.com/blockly-website/blockly-student-tracker/blob/main/next.config.ts"
  click NextApp "https://github.com/blockly-website/blockly-student-tracker/blob/main/.env.example"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#dbeafe,stroke:#1d4ed8,stroke-width:1px,color:#0b1b3a
  classDef dataaccess fill:#bfdbfe,stroke:#1e40af,stroke-width:1px,color:#0b1b3a
  classDef state fill:#e0f2fe,stroke:#0369a1,stroke-width:1px,color:#062b3b
  classDef localstore fill:#f1f5f9,stroke:#475569,stroke-width:1px,color:#0f172a

  classDef supabase fill:#dcfce7,stroke:#16a34a,stroke-width:1px,color:#052e16
  classDef db fill:#bbf7d0,stroke:#15803d,stroke-width:1px,color:#052e16
  classDef security fill:#fff7ed,stroke:#ea580c,stroke-width:2px,color:#4a1a05

  classDef external fill:#e5e7eb,stroke:#374151,stroke-width:1px,color:#111827
  classDef platform fill:#e5e7eb,stroke:#6b7280,stroke-width:1px,color:#111827
  classDef dev fill:#f3f4f6,stroke:#9ca3af,stroke-width:1px,color:#111827,stroke-dasharray: 6 4
```
