# lazyjerry/pro-dig-studio architecture

> Architecture diagram of the GitHub repository lazyjerry/pro-dig-studio, 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/lazyjerry/pro-dig-studio
- Repository: https://github.com/lazyjerry/pro-dig-studio

## Overview

##### Project Type and Purpose
- This is a full-stack, serverless edge application built on **Cloudflare Workers** using **Hono** as the routing framework.
- Purpose: Provide authenticated CRUD services for worklogs, quotes, meetings, labor reports, notebooks, and external link management; render HTML/PDF templates; and serve a static frontend.

##### File Structure
- Top level:
- `public/` – Static assets (HTML, CSS, JS) served to the browser
- `src/` – All TypeScript code for the Workers runtime
- `sql/init.sql` – D1 database schema migrations
- `wrangler.jsonc`/`package.json`/`tsconfig.json` – Configuration, dependencies, build
- Inside `src/`:
- `index.ts` – Hono application entry point, environment bindings (D1, KV, Secrets)
- `libs/` – Reusable modules (JWT issuance/verification, config loader, common middleware)
- `routes/` – Route handlers and auth middleware (`authRequired.ts`, `data.ts`, `worklogs.ts`)
- `templates/` – Dynamic HTML/PDF templates (e.g. `labor.html`+`labor.ts`)

##### Extract Key Architecture from the README
- **Edge platform**: Cloudflare Workers
- **Database**: D1 (SQLite-compatible)
- **Cache/kv**: Cloudflare KV Namespace for sessions or speed caching
- **Secrets**: JWT_SECRET for signing tokens
- **Framework**: Hono for routing and middleware
- **Frontend**: Static JSON import/export, PDF download, WebAuthn authentication

##### Components & Interactions (
a. Main Components:
- **Browser/Client**: Initiates HTTP(S) requests (static pages, API calls, WebAuthn flows)
- **Cloudflare Workers (Hono App)**
- Static file handler (serves `public/*`)
- Route handlers: `/`, `/auth*`, `/data*`, `/worklogs*`, `/cache*`
- Middleware layer: JWT + Cookie auth (`authRequired.ts`)
- **D1 Database**: Persistent SQL storage for items, worklogs, users
- **KV Namespace**: Fast key–value store for session or temporary data
- **Secrets**: JWT_SECRET binding for token operations
- **External Systems** (implicit): WebAuthn authenticators in browser, PDF renderer built via HTML templates
b. Relationships & Data Flows:
1. Browser → Worker
- GET `/dashboard.html`, `/labor/index.html` → Static assets served from `public/`
- POST `/webauthn/register` or `/webauthn/login` → Hono route → KV & D1
- API calls (`/data`, `/worklogs`) → Hono route → D1 writes/reads
2. Worker (Hono) → D1
- CRUD statements prepared in `data.ts` and `worklogs.ts`
3. Worker → KV
- Session data or WebAuthn challenge storage
4. Worker Middleware
- `authRequired.ts` inspects cookies, JWT_SECRET, KV to allow/block
5. Worker → Browser
- JSON responses, HTML views via `templates/*.ts`, PDF streams
c. Architectural Patterns & Principles:
- **Serverless at the edge**: single Hono app handles both static and dynamic routes
- **Middleware** for cross-cutting concerns (authentication, JSON parsing)
- **Layered** structure: Controllers (routes) → Services (libs) → Data layer (D1/KV) → Templates
- **Environment binding** for resources: all I/O abstracted behind `c.env.DB`, `c.env.KV`, `c.env.JWT_SECRET`
d. Key Technologies & Libraries:
- Cloudflare Workers + Wrangler (deployment)
- Hono framework (TypeScript)
- D1 (SQLite) & KV Namespaces
- JSON Web Tokens + WebAuthn (no-password auth)
- Static assets in `public/` (TailwindCSS, vanilla JS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side" 
        Browser["Browser / Client"]:::client
        Dashboard["dashboard.html"]:::asset
        AuthPage["auth.html"]:::asset
        LaborIndex["labor/index.html"]:::asset
        LaborDetail["labor/detail.html"]:::asset
        MeetingIndex["meeting/index.html"]:::asset
        MeetingDetail["meeting/detail.html"]:::asset
        QuoteIndex["quote/index.html"]:::asset
        QuoteDetail["quote/detail.html"]:::asset
        NoteIndex["note/index.html"]:::asset
        WorklogsIndex["work-logs/index.html"]:::asset
        StaticAssets["Static Assets (CSS/JS)"]:::asset
    end
    click Browser "https://github.com/lazyjerry/pro-dig-studio/tree/master/ProGigStudio/public/"
    click Dashboard "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/dashboard.html"
    click AuthPage "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/auth.html"
    click LaborIndex "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/labor/index.html"
    click LaborDetail "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/labor/detail.html"
    click MeetingIndex "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/meeting/index.html"
    click MeetingDetail "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/meeting/detail.html"
    click QuoteIndex "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/quote/index.html"
    click QuoteDetail "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/quote/detail.html"
    click NoteIndex "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/note/index.html"
    click WorklogsIndex "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/public/work-logs/index.html"
    click StaticAssets "https://github.com/lazyjerry/pro-dig-studio/tree/master/ProGigStudio/public/css/"

    %% Edge (Cloudflare Workers)
    subgraph "Edge (Cloudflare Workers)" 
        HonoApp["Hono App (Workers)"]:::compute
        ServePublic["Static Content Handler"]:::compute
        subgraph "API Layer"
            AuthMiddleware["authRequired.ts"]:::compute
            DataRoutes["data.ts"]:::compute
            WorklogRoutes["worklogs.ts"]:::compute
        end
        subgraph "Template Renderer"
            LaborTemplate["labor.html & labor.ts"]:::compute
            MeetingTemplate["meeting.html & meeting.ts"]:::compute
            QuoteTemplate["quote.html & quote.ts"]:::compute
        end
        subgraph "Libs / Utilities"
            Common["common.ts"]:::compute
            ConfigLoader["config.ts"]:::compute
            JWTUtils["jwt.ts"]:::compute
        end
    end
    click HonoApp "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/index.ts"
    click AuthMiddleware "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/routes/authRequired.ts"
    click DataRoutes "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/routes/data.ts"
    click WorklogRoutes "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/routes/worklogs.ts"
    click Common "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/libs/common.ts"
    click ConfigLoader "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/libs/config.ts"
    click JWTUtils "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/libs/jwt.ts"
    click LaborTemplate "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/templates/labor.html"
    click LaborTemplate "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/templates/labor.ts"
    click MeetingTemplate "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/templates/meeting.html"
    click MeetingTemplate "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/templates/meeting.ts"
    click QuoteTemplate "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/templates/quote.html"
    click QuoteTemplate "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/src/templates/quote.ts"

    %% Resources
    subgraph "Resources" 
        D1DB["D1 Database"]:::storage
        KVStore["KV Namespace"]:::storage
        Secrets["JWT_SECRET (env)"]:::secret
    end
    click D1DB "https://github.com/lazyjerry/pro-dig-studio/blob/master/sql/init.sql"
    click Secrets "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/wrangler.jsonc"

    %% Configuration & Project Files
    subgraph "Config & Project Files"
        WranglerCfg["wrangler.jsonc"]:::secret
        WorkerDef["worker-configuration.d.ts"]:::secret
        PackageJSON["package.json"]:::config
        TSConfig["tsconfig.json"]:::config
        README["README.md"]:::config
        License["LICENSE"]:::config
    end
    click WranglerCfg "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/wrangler.jsonc"
    click WorkerDef "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/worker-configuration.d.ts"
    click PackageJSON "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/package.json"
    click TSConfig "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/tsconfig.json"
    click README "https://github.com/lazyjerry/pro-dig-studio/blob/master/ProGigStudio/README.md"
    click License "https://github.com/lazyjerry/pro-dig-studio/tree/master/ProGigStudio/LICENSE"

    %% Flows
    Browser --> ServePublic
    Browser --> AuthMiddleware
    Browser --> DataRoutes
    Browser --> WorklogRoutes
    ServePublic -->|"serves static files"| Browser
    AuthMiddleware -->|"auth checks"| KVStore
    AuthMiddleware -->|"uses secret"| Secrets
    DataRoutes -->|"CRUD operations"| D1DB
    WorklogRoutes -->|"CRUD operations"| D1DB
    HonoApp --> ServePublic
    HonoApp --> AuthMiddleware
    HonoApp --> DataRoutes
    HonoApp --> WorklogRoutes
    HonoApp --> LaborTemplate
    HonoApp --> MeetingTemplate
    HonoApp --> QuoteTemplate
    HonoApp --> Common
    HonoApp --> ConfigLoader
    HonoApp --> JWTUtils
    HonoApp --> D1DB
    HonoApp --> KVStore
    HonoApp --> Secrets
    LaborTemplate -->|"renders HTML/PDF"| Browser
    MeetingTemplate -->|"renders HTML/PDF"| Browser
    QuoteTemplate -->|"renders HTML/PDF"| Browser

    %% Styles
    classDef client fill:#f9d5a2,stroke:#e28f30
    classDef compute fill:#a2cfff,stroke:#1f78b4
    classDef storage fill:#b3ffb3,stroke:#2ca02c
    classDef secret fill:#e2caff,stroke:#6a0dad
    classDef config fill:#ffc2c2,stroke:#d62728
    classDef asset fill:#ffe680,stroke:#ffbf00
```
