# ccbikai/sink architecture

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

- Interactive diagram: https://gitdiagram.com/ccbikai/sink
- Repository: https://github.com/ccbikai/sink

## Overview

##### Project Type and Purpose
- Sink is a full-stack, serverless link-shortening application with built-in analytics.
- The frontend is a Nuxt.js SPA (in the `app/` folder), and the backend consists of Cloudflare Workers (under `server/api/…`) that provide RESTful endpoints, leverage Workers KV for storage, and use the Cloudflare Analytics Engine (and optional Workers AI) for metrics and AI-driven slug generation.

##### File Structure Analysis
- Top-level
- `app/` – Nuxt 3 application: components, pages, layouts, middleware, composables, assets, utils, i18n.
- `server/` – Cloudflare Workers APIs: routing files (`api/`), middleware, utilities, and `wrangler.toml`.
- `public/` – Static assets: geojson, manifest, images.
- `schemas/` – TypeScript schemas for request/response validation.
- `scripts/` – Build scripts for pre-processing (e.g., maps, colo data).
- Config files: `nuxt.config.ts`, `tailwind.config.js`, `tsconfig.json`, `wrangler.toml`, `.env.example`.

##### README Insights
- Confirms serverless architecture on Cloudflare Pages + Workers.
- Highlights dependencies: KV for storage, Analytics Engine for stats, Workers AI for AI-powered slug creation.
- Deployment instructions show environment bindings (`NUXT_*`, `KV`, `ANALYTICS`, `AI`).

a. Main Components
- Client (Browser/Mobile) running the Nuxt frontend
- Cloudflare Pages hosting the static SPA
- Cloudflare Workers HTTP APIs (CRUD for links, analytics queries)
- Workers KV Namespace (persisting link records, slugs, metadata)
- Cloudflare Analytics Engine (storing/fetching metrics: views, counters)
- Optional Workers AI Catalog (AI slug generation)
- External Services: GeoJSON data, third-party libraries (shadcn/ui, Tailwind, i18n)

b. Relationships & Interactions
- Browser ↔ Nuxt SPA (HTTP/HTTPS)
- SPA calls Worker API endpoints (fetch/create/edit/delete links, query analytics)
- Worker API → KV (read/write link data)
- Worker API → Analytics Engine (query metrics dataset)
- Worker API → Workers AI (optional AI slug generation)
- Workers middleware (auth, redirects) intercepts and applies logic

c. Architectural Patterns & Principles
- Serverless microservices: each endpoint in `server/api/…` is an isolated function
- Clear separation of concerns:
– Presentation layer (Nuxt components, pages)
– API layer (Workers functions + middleware)
– Data layer (KV, Analytics)
- Declarative configuration via `nuxt.config.ts`, `wrangler.toml`, Tailwind config
- Use of schema validation (`schemas/`) for type safety

d. Relevant Technologies
- Frontend: Nuxt 3, Vue components, Tailwind CSS, shadcn-vue, i18n
- Backend: Cloudflare Workers, Wrangler, TypeScript, Workers KV, Analytics Engine, Workers AI
- Build/Dev: pnpm, ESLint, scripts in `scripts/`, CI via GitHub Actions (implied by `.github/`)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Browser["Browser/Mobile"]:::external
        Pages["Cloudflare Pages"]:::frontend
        SPA["Nuxt SPA"]:::frontend
        I18n["i18n Module"]:::frontend
        SPA --> I18n
        Pages --> SPA
        Browser -->|"HTTP/HTTPS"| Pages
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        subgraph "Middleware"
            direction TB
            RedirectMW["Redirect Middleware"]:::backend
            AuthMW["Authentication Middleware"]:::backend
        end

        subgraph "Services"
            direction TB
            LinkService["Cloudflare Worker: Link Service"]:::backend
            AnalyticsService["Cloudflare Worker: Analytics Service"]:::backend
            LogsService["Cloudflare Worker: Logs Service"]:::backend
            VerifyEP["Cloudflare Worker: Verification Endpoint"]:::backend
        end

        %% Middleware chain
        RedirectMW --> AuthMW
        AuthMW --> LinkService
        AuthMW --> AnalyticsService
        AuthMW --> LogsService
        AuthMW --> VerifyEP
    end

    %% Optional AI Service
    AIService["Workers AI (Slug Generation)"]:::ai

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        KV["Workers KV Namespace"]:::datastore
        AnalyticsEngine["Cloudflare Analytics Engine"]:::datastore
    end

    %% Static & Config
    subgraph "Static & Config"
        direction TB
        Public["Static Assets"]:::external
        Schemas["Schemas"]:::external
        Scripts["Build Scripts"]:::external
        WranglerCFG["wrangler.toml"]:::external
    end

    %% Interactions
    SPA -->|"API Calls"| RedirectMW
    LinkService -->|"Read/Write Links"| KV
    LinkService -->|"AI Slug Gen"| AIService
    AnalyticsService -->|"Query Metrics"| AnalyticsEngine
    LogsService -->|"Log Events"| KV
    VerifyEP -->|"Verify Requests"| KV

    %% Click Events
    click SPA "https://github.com/ccbikai/sink/tree/master/app/"
    click LinkService "https://github.com/ccbikai/sink/tree/master/server/api/link/"
    click RedirectMW "https://github.com/ccbikai/sink/blob/master/server/middleware/1.redirect.ts"
    click AuthMW "https://github.com/ccbikai/sink/blob/master/server/middleware/2.auth.ts"
    click AIService "https://github.com/ccbikai/sink/blob/master/server/api/link/ai.get.ts"
    click LinkService "https://github.com/ccbikai/sink/blob/master/server/api/link/create.post.ts"
    click LinkService "https://github.com/ccbikai/sink/blob/master/server/api/link/delete.post.ts"
    click LinkService "https://github.com/ccbikai/sink/blob/master/server/api/link/edit.put.ts"
    click LinkService "https://github.com/ccbikai/sink/blob/master/server/api/link/list.get.ts"
    click LinkService "https://github.com/ccbikai/sink/blob/master/server/api/link/query.get.ts"
    click LinkService "https://github.com/ccbikai/sink/blob/master/server/api/link/search.get.ts"
    click LinkService "https://github.com/ccbikai/sink/blob/master/server/api/link/upsert.post.ts"
    click AnalyticsService "https://github.com/ccbikai/sink/tree/master/server/api/stats/"
    click AnalyticsService "https://github.com/ccbikai/sink/blob/master/server/api/stats/counters.get.ts"
    click AnalyticsService "https://github.com/ccbikai/sink/blob/master/server/api/stats/metrics.get.ts"
    click AnalyticsService "https://github.com/ccbikai/sink/blob/master/server/api/stats/views.get.ts"
    click LogsService "https://github.com/ccbikai/sink/blob/master/server/api/logs/events.ts"
    click LogsService "https://github.com/ccbikai/sink/blob/master/server/api/logs/locations.ts"
    click VerifyEP "https://github.com/ccbikai/sink/blob/master/server/api/verify.ts"
    click KV "https://github.com/ccbikai/sink/blob/master/wrangler.toml"
    click AnalyticsEngine "https://github.com/ccbikai/sink/blob/master/wrangler.toml"
    click Public "https://github.com/ccbikai/sink/tree/master/public/"
    click Schemas "https://github.com/ccbikai/sink/tree/master/schemas/"
    click Scripts "https://github.com/ccbikai/sink/tree/master/scripts/"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#1976D2,color:#0D47A1;
    classDef backend fill:#E8F5E9,stroke:#388E3C,color:#1B5E20;
    classDef datastore fill:#FFF3E0,stroke:#F57C00,color:#E65100;
    classDef ai fill:#F3E5F5,stroke:#8E24AA,color:#4A148C;
    classDef external fill:#ECEFF1,stroke:#78909C,color:#263238;
```
