# studioconcertos/quartz architecture

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

- Interactive diagram: https://gitdiagram.com/studioconcertos/quartz
- Repository: https://github.com/studioconcertos/quartz

## Overview

##### Project Type and Purpose
- Quartz is a full-stack web application: an open-source, Nuxt 3-based slides engine for building and delivering ambitious presentations.
- The README calls out core use cases (landing pages, authentication, slide editing “Atelier,” real-time live view) and the tech stack (Nuxt 3, Supabase, UnoCSS).

##### File Structure
- Top-level directories:
- assets (GLSL shaders, static assets)
- components (UI building blocks, subdivided by feature: atelier, auth, dashboard, landing, node-components)
- layouts (Nuxt layouts)
- pages (routing: landing, auth, atelier, live, index)
- stores (Pinia/Vue stores for state: assets, atelier, auth, deck)
- composables (reusable hooks: context menu, element renderer, snapshot)
- server (Nuxt server routes or API endpoints, tsconfig for server‐side code)
- utils & types (helpers, TypeScript definitions)
- Config and build files: nuxt.config.ts, tsconfig.json, bun.lockb, package.json, .env.example, uno.config.ts

##### README Insights
- Confirms use of Supabase for Auth, Database (Postgres), Storage, Real-time.
- Emphasizes three main UIs: landing, dashboard/auth, atelier (slide editor), live view.

a. Main Components
- Client (Browser) running Nuxt 3 front-end
– Pages and layouts rendered via SSR/SPA
– Component tree: landing, auth, dashboard, atelier, live modules
– State management via Pinia stores and composables
– Asset pipeline: shaders, images, CSS (UnoCSS)
- API/Server layer (Nuxt server routes in server/)
– Custom endpoints if any (e.g., webhooks, business logic not in Supabase)
- Supabase Services
– Authentication (magic links, OAuth)
– Database (users, decks, slides, elements)
– Storage (images, assets)
– Real-time (subscriptions for live sessions)
- External Deployment/Hosting
– CI/CD (GitHub Actions), hosting (Vercel/Netlify/Edge functions)

b. Relationships and Data Flows
- Browser ↔ Supabase Auth (login/logout)
- Browser ↔ Supabase Database (CRUD decks, slides via client SDK)
- Browser ↔ Supabase Storage (upload/download assets)
- Browser ↔ Supabase Real-time (WebSocket) for live sessions and Atelier syncing
- Browser ↔ Nuxt Server Routes (if custom logic exists)
- Hosting/CD pipeline pulls from GitHub on push → builds Nuxt app → deploys static and server functions

c. Architectural Patterns & Design Principles
- Component-based UI (Vue 3 + Nuxt)
- Feature modules (atelier, auth, dashboard, landing, live)
- Separation of concerns:
– Pages for routing
– Components for UI
– Composables for logic
– Stores for state
- API-first / BaaS approach via Supabase
- Real-time synchronization for collaborative editing and live view

d. Key Technologies
- Nuxt 3 (SSR/SPA, file-based routing, server routes)
- Vue 3 components, Composition API (composables)
- Pinia for state
- Supabase JS SDK (Auth, Database, Storage, Realtime)
- UnoCSS for utility-first styling
- WebGL shaders (assets/shaders) for slide animations
- Bun or Node (bun.lockb vs package.json) for build/runtime

##### Crucial Details to Capture
- Client architecture: pages→components→stores→composables
- BaaS interactions: authentication, CRUD, real-time
- Asset usage: GLSL shaders and static assets
- Deployment pipeline and runtime environment

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Client Layer
  subgraph "Nuxt Front-end (Client)"
    direction TB
    NuxtApp["Nuxt 3 Front-end"]:::frontend
    subgraph "Core"
      direction TB
      AppVue["app.vue"]:::frontend
      NuxtConfig["nuxt.config.ts"]:::frontend
      DefaultLayout["layouts/default.vue"]:::frontend
    end
    subgraph "Pages"
      direction TB
      LandingPage["pages/index.vue"]:::frontend
      AuthPage["pages/auth/index.vue"]:::frontend
      AuthCallback["pages/auth/callback.vue"]:::frontend
      WorkshopPage["pages/atelier/index.vue"]:::frontend
      WorkshopDetail["pages/atelier/[id].vue"]:::frontend
      LiveView["pages/live/[id].vue"]:::frontend
    end
    subgraph "Components"
      direction TB
      subgraph "Landing"
        Hero["Hero.vue"]:::frontend
        Navbar["Navbar.vue"]:::frontend
      end
      subgraph "Auth"
        SignInForm["SignInForm.vue"]:::frontend
        RegisterForm["RegisterForm.vue"]:::frontend
      end
      subgraph "Dashboard"
        DashboardHeader["Header.vue"]:::frontend
        Sidebar["Sidebar.vue"]:::frontend
        DeckComp["Deck.vue"]:::frontend
      end
      subgraph "Atelier"
        AtelierHeader["Header.vue"]:::frontend
        Toolbar["Toolbar.vue"]:::frontend
        subgraph "Inspector"
          AssetsView["Assets.vue"]:::frontend
          HierarchyView["Hierarchy.vue"]:::frontend
          PropertiesView["Properties.vue"]:::frontend
        end
        subgraph "Render"
          ElementRender["Element.vue"]:::frontend
          SnapshotRender["Snapshot.vue"]:::frontend
        end
        subgraph "Timeline"
          FrameComp["Frame.vue"]:::frontend
        end
      end
    end
    subgraph "Stores"
      direction TB
      AssetsStore["useAssetsStore.ts"]:::frontend
      AtelierStore["useAtelierStore.ts"]:::frontend
      AuthStore["useAuthStore.ts"]:::frontend
      DeckStore["useDeckStore.ts"]:::frontend
    end
    subgraph "Composables"
      direction TB
      ContextMenu["useContextMenu.ts"]:::frontend
      ElementRenderer["useElementRenderer.ts"]:::frontend
      SnapshotHook["useSnapshot.ts"]:::frontend
    end
    subgraph "Assets & Shaders"
      direction TB
      ShaderVert["vertex.glsl"]:::frontend
      ShaderFrag["fragment.glsl"]:::frontend
    end
  end

  %% API Layer
  subgraph "Nuxt Server Routes / API" 
    direction TB
    ServerConfig["server/tsconfig.json"]:::api
    ServerRoutes["Custom Endpoints"]:::api
  end

  %% Supabase BaaS
  subgraph "Supabase Services"
    direction TB
    AuthService["Auth"]:::supabase
    DatabaseService["Database"]:::supabase
    StorageService["Storage"]:::supabase
    RealtimeService["Realtime"]:::supabase
  end

  %% External Infrastructure
  subgraph "CI/CD & Hosting"
    direction TB
    GitHub["GitHub Actions"]:::infra
    Hosting["Vercel / Netlify"]:::infra
  end

  %% Connections
  NuxtApp -->|"HTTP/WS via Supabase SDK"| AuthService
  NuxtApp -->|"HTTP/WS via Supabase SDK"| DatabaseService
  NuxtApp -->|"HTTP/WS via Supabase SDK"| StorageService
  NuxtApp -->|"WebSocket via Supabase SDK"| RealtimeService
  NuxtApp -->|"HTTP"| ServerRoutes

  GitHub -->|"Deploy"| Hosting
  Hosting -->|"Serves"| NuxtApp

  %% Click Events
  click AppVue "https://github.com/studioconcertos/quartz/blob/main/app.vue"
  click NuxtConfig "https://github.com/studioconcertos/quartz/blob/main/nuxt.config.ts"
  click DefaultLayout "https://github.com/studioconcertos/quartz/blob/main/layouts/default.vue"
  click LandingPage "https://github.com/studioconcertos/quartz/blob/main/pages/index.vue"
  click Hero "https://github.com/studioconcertos/quartz/blob/main/components/landing/Hero.vue"
  click Navbar "https://github.com/studioconcertos/quartz/blob/main/components/landing/Navbar.vue"
  click AuthPage "https://github.com/studioconcertos/quartz/blob/main/pages/auth/index.vue"
  click AuthCallback "https://github.com/studioconcertos/quartz/blob/main/pages/auth/callback.vue"
  click SignInForm "https://github.com/studioconcertos/quartz/blob/main/components/auth/SignInForm.vue"
  click RegisterForm "https://github.com/studioconcertos/quartz/blob/main/components/auth/RegisterForm.vue"
  click AuthStore "https://github.com/studioconcertos/quartz/blob/main/stores/useAuthStore.ts"
  click DashboardHeader "https://github.com/studioconcertos/quartz/blob/main/components/dashboard/Header.vue"
  click Sidebar "https://github.com/studioconcertos/quartz/blob/main/components/dashboard/Sidebar.vue"
  click DeckComp "https://github.com/studioconcertos/quartz/blob/main/components/dashboard/Deck.vue"
  click DeckStore "https://github.com/studioconcertos/quartz/blob/main/stores/useDeckStore.ts"
  click WorkshopPage "https://github.com/studioconcertos/quartz/blob/main/pages/atelier/index.vue"
  click WorkshopDetail "https://github.com/studioconcertos/quartz/blob/main/pages/atelier/[id].vue"
  click AtelierHeader "https://github.com/studioconcertos/quartz/blob/main/components/atelier/Header.vue"
  click Toolbar "https://github.com/studioconcertos/quartz/blob/main/components/atelier/Toolbar.vue"
  click AssetsView "https://github.com/studioconcertos/quartz/blob/main/components/atelier/inspector/view/Assets.vue"
  click HierarchyView "https://github.com/studioconcertos/quartz/blob/main/components/atelier/inspector/view/Hierarchy.vue"
  click PropertiesView "https://github.com/studioconcertos/quartz/blob/main/components/atelier/inspector/view/Properties.vue"
  click ElementRender "https://github.com/studioconcertos/quartz/blob/main/components/atelier/render/Element.vue"
  click SnapshotRender "https://github.com/studioconcertos/quartz/blob/main/components/atelier/render/Snapshot.vue"
  click FrameComp "https://github.com/studioconcertos/quartz/blob/main/components/atelier/timeline/Frame.vue"
  click AtelierStore "https://github.com/studioconcertos/quartz/blob/main/stores/useAtelierStore.ts"
  click LiveView "https://github.com/studioconcertos/quartz/blob/main/pages/live/[id].vue"
  click AssetsStore "https://github.com/studioconcertos/quartz/blob/main/stores/useAssetsStore.ts"
  click ContextMenu "https://github.com/studioconcertos/quartz/blob/main/composables/useContextMenu.ts"
  click ElementRenderer "https://github.com/studioconcertos/quartz/blob/main/composables/useElementRenderer.ts"
  click SnapshotHook "https://github.com/studioconcertos/quartz/blob/main/composables/useSnapshot.ts"
  click ShaderVert "https://github.com/studioconcertos/quartz/blob/main/assets/shaders/hero/vertex.glsl"
  click ShaderFrag "https://github.com/studioconcertos/quartz/blob/main/assets/shaders/hero/fragment.glsl"
  click ServerConfig "https://github.com/studioconcertos/quartz/blob/main/server/tsconfig.json"

  %% Styles
  classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:1px
  classDef api fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px
  classDef supabase fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
  classDef infra fill:#e0e0e0,stroke:#757575,stroke-width:1px
```
