# bytemystique/the-woven-chronicle architecture

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

- Interactive diagram: https://gitdiagram.com/bytemystique/the-woven-chronicle
- Repository: https://github.com/bytemystique/the-woven-chronicle

## Overview

##### Project type and purpose
- Type: A full-stack, single-page web application built with Vite and vanilla JavaScript, leveraging a Backend-as-a-Service (Supabase) for real-time collaboration and persistent storage.
- Purpose: “The Woven Chronicle” is a chaotic, collaborative storytelling platform where users add sentences in real time and a small on-device AI weaves them together, using Supabase for data sync and persistence and Vercel for static hosting.

##### File structure
- Top-level
- LICENSE, README.md
- db/schema.sql → database schema for Supabase Postgres
- web/ → contains the entire front-end app
- web/
- package.json, package-lock.json, vite.config.js → build and dependency management
- .env.example → environment variables (Supabase URL/keys)
- index.html, admin-local.html → entry points for production and local admin view
- main.js → bundles client-side logic (boots the SPA)
- src/ → application modules (UI components, CSS, business logic)
- processor.js, peer-processor.js → client-side AI/text-weaving logic
- public/ → static assets
- No custom backend code: all server-side logic is outsourced to Supabase (Postgres + Realtime).

##### README for additional insights
- Uses @supabase/supabase-js for real-time DB updates and auth-free access
- Web Audio API for sound effects
- Hosted on Vercel as a static site, with live updates handled via Supabase WebSockets

a. Main components
- Web Client (browser)
– UI layer (HTML/CSS, src/*.js)
– AI Processor (processor.js + peer-processor.js)
– Realtime Sync (supabase-js library)
– Sound Engine (Web Audio API)
- Supabase Service
– Postgres Database (db/schema.sql)
– Realtime Engine (WebSockets)
- Vercel Hosting
– Static file CDN (serves built JS/CSS/HTML)
b. Relationships and interactions
- Browser ←HTTPS— Vercel (initial page load)
- Browser ⇄ WebSockets/HTTPS— Supabase Realtime & REST endpoints
- AI Processor runs entirely on the client and reads/writes to the local state, then pushes changes to Supabase
c. Architectural patterns and principles
- Client-centric architecture with BaaS (Backend-as-a-Service)
- Event-driven updates (pub/sub via Supabase Realtime)
- Single-page application (SPA) model using Vite
- On-device computation (minimizes server cost, boosts privacy)
d. Key technologies
- Vite (dev server, bundler)
- Vanilla JavaScript, HTML, CSS
- @supabase/supabase-js (Realtime + Postgres client)
- Web Audio API (typewriter blips)
- Vercel (static hosting CDN)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Deployment and Hosting Layer
    subgraph "Deployment & Hosting"
        Build["Vite Build"]:::build
        CDN["Vercel CDN"]:::service
    end

    %% Browser Client Layer
    subgraph "Browser Client"
        UI["Browser UI"]:::client
        State["Realtime Sync (supabase-js)"]:::client
        AI["On-device AI Engine"]:::client
        Audio["Audio Engine (Web Audio API)"]:::client
    end

    %% Supabase BaaS Layer
    subgraph "Supabase BaaS"
        Realtime["Supabase Realtime"]:::service
        Postgres["Supabase Postgres"]:::service
    end

    %% Build and Deploy
    Build -->|deploy| CDN
    CDN -->|HTTPS| UI

    %% Client Interactions
    UI -->|user input| AI
    AI -->|weave text| UI
    UI -->|trigger sound| Audio
    UI -->|sync calls| State

    %% Realtime and REST flows
    State -->|WebSocket| Realtime
    State -->|REST API| Postgres
    Realtime -->|events| State

    %% Click Events
    click UI "https://github.com/bytemystique/the-woven-chronicle/blob/main/web/index.html"
    click State "https://github.com/bytemystique/the-woven-chronicle/blob/main/web/src/main.js"
    click AI "https://github.com/bytemystique/the-woven-chronicle/blob/main/web/processor.js"
    click Build "https://github.com/bytemystique/the-woven-chronicle/blob/main/web/package.json"
    click CDN "https://github.com/bytemystique/the-woven-chronicle/tree/main/web/public/"
    click Postgres "https://github.com/bytemystique/the-woven-chronicle/blob/main/db/schema.sql"

    %% Styles
    classDef service fill:#B3CDE3,stroke:#6497B1,stroke-width:2px
    classDef client fill:#C7E9B4,stroke:#67A61E,stroke-width:2px
    classDef build fill:#FDD0A2,stroke:#FB8B24,stroke-width:2px
```
