Skip to content

Overview

Jump to bottom
Dave Williams edited this page Jun 16, 2025 · 1 revision

Overview

Relevant source files from the codebase:

This document provides a comprehensive overview of the dave.io platform, a modern personal website and API platform built on Nuxt 3 and Cloudflare Workers. The system serves as both a frontend application and a robust backend API with AI integration, image processing, and authentication services.

For detailed information about specific subsystems, see Core Architecture, API System, Authentication & Security, Frontend & User Interface, and Development Environment.

System Purpose and Architecture

The dave.io platform combines a Vue.js frontend with a serverless backend to deliver:

  • Personal Website: Modern web interface with cyberpunk theming
  • API Platform: RESTful APIs with JWT authentication and comprehensive OpenAPI documentation
  • AI Services: Image alt-text generation and ticket management using Cloudflare AI
  • Image Processing: Optimization and transformation via Cloudflare Images
  • URL Redirection: Short link management with analytics
  • Developer Tools: Comprehensive CLI utilities for development and operations

Overall System Architecture

graph TB
    User[User/Client] --> CF[Cloudflare Edge Network]
    CF --> Worker[Cloudflare Worker]
    Worker --> Nuxt[Nuxt 3 Application]
    
    Nuxt --> API[API Endpoints]
    Nuxt --> Frontend[Vue.js Frontend]
    
    API --> Auth[JWT Authentication]
    API --> AI[Cloudflare AI]
    API --> Images[Cloudflare Images]
    API --> KV[Cloudflare KV]
    API --> D1[Cloudflare D1]
    
    Auth --> Permissions[Hierarchical Permissions]
    AI --> LLAVA[LLAVA Vision Model]
    AI --> TextModel[Text Generation Model]
    
    KV --> Metrics[Metrics Storage]
    KV --> Redirects[URL Redirects]
    D1 --> TokenDB[Token Metadata]
    
    CLI[CLI Tools] --> API
    CLI --> KV
    CLI --> D1
Loading

Core Technology Stack

Layer Technology Purpose Configuration
Runtime Nuxt 3 Full-stack Vue.js framework nuxt.config.ts
Deployment Cloudflare Workers Serverless edge computing wrangler.jsonc
Language TypeScript Type-safe development package.json
Package Manager Bun Fast JavaScript runtime package.json
Validation Zod Schema validation and OpenAPI package.json
Authentication JWT + JOSE Token-based auth with hierarchical permissions package.json
Testing Vitest Unit and integration testing package.json
Code Quality Biome + Trunk Formatting and linting package.json

Sources: package.json, wrangler.jsonc

Core System Components

graph LR
    Request[HTTP Request] --> Auth[Authentication Layer]
    Auth --> Valid{Valid Token?}
    Valid -->|Yes| Endpoint[API Endpoint]
    Valid -->|No| Error[401 Error]
    
    Endpoint --> Validation[Schema Validation]
    Validation --> Business[Business Logic]
    Business --> Response[Standardized Response]
    
    Business --> Services[External Services]
    Services --> AI[Cloudflare AI]
    Services --> Images[Cloudflare Images]
    Services --> KV[KV Storage]
    Services --> D1[D1 Database]
    
    Response --> Metrics[Async Metrics]
    Metrics --> KV
Loading

Sources: server/utils/auth.ts, server/utils/schemas.ts, server/utils/response.ts, bin/try.ts, bin/jwt.ts, bin/kv.ts

Request Processing Flow

The system processes requests through a standardized pipeline:

  1. Route Resolution: Nuxt 3 automatically discovers API endpoints based on file naming conventions in server/api/
  2. Authentication: JWT tokens extracted via extractToken() and verified using verifyJWT()
  3. Validation: Request bodies validated against Zod schemas via schema.parse()
  4. Business Logic: Core functionality implemented with Cloudflare service bindings
  5. Response Formatting: All responses standardized via createApiResponse()
  6. Metrics Collection: Request metrics recorded to KV storage asynchronously

Sources: server/utils/auth.ts, server/utils/response.ts, server/utils/schemas.ts

Development Workflow

Schema-First API Design

graph TD
    Schema[Define Zod Schema] --> Validation[Add .openapi() metadata]
    Validation --> Endpoint[Implement API endpoint]
    Endpoint --> Parse[Use schema.parse()]
    Parse --> Response[Return createApiResponse()]
    Response --> Generate[Run generate:openapi]
    Generate --> Documentation[Updated OpenAPI spec]
Loading

Quality Assurance Pipeline

Command Purpose Tools Used
bun run lint:biome Code formatting and basic linting Biome
bun run lint:trunk Multi-linter analysis Trunk CLI
bun run lint:types TypeScript type checking tsc
bun run test Unit test execution Vitest
bun run test:api HTTP API integration tests Custom CLI
bun run check Complete validation pipeline All tools

Sources: package.json

File Organization

Core Directories

Path Purpose Key Files
server/api/ API endpoint definitions *.get.ts, *.post.ts
server/utils/ Shared utilities and helpers auth.ts, schemas.ts, response.ts
server/middleware/ Request processing middleware auth.ts, metrics.ts
bin/ CLI tools and utilities try.ts, jwt.ts, kv.ts
test/ Test files *.test.ts
types/ TypeScript type definitions api.ts
data/kv/ KV storage initialization data _init.yaml

API Endpoint Naming

The system uses file-based routing with HTTP method suffixes:

  • server/api/ping.get.ts → GET /api/ping
  • server/api/ai/alt.post.ts → POST /api/ai/alt
  • server/api/tokens/[uuid].get.ts → GET /api/tokens/{uuid}
  • server/routes/go/[slug].get.ts → GET /go/{slug}

Sources: README.md, AGENTS.md

Authentication and Permissions

The system implements hierarchical JWT permissions where parent scopes grant access to child resources:

graph TD
    Wildcard["* (Admin)"] --> Everything[All Endpoints]
    API[api] --> APITokens[api:tokens]
    API --> APIMetrics[api:metrics]
    AI[ai] --> AIAlt[ai:alt]
    AI --> AITickets[ai:tickets]
    Dashboard[dashboard] --> DashStats[dashboard:stats]
    Admin[admin] --> AdminUsers[admin:users]
    
    Everything --> APITokens
    Everything --> APIMetrics
    Everything --> AIAlt
    Everything --> AITickets
    Everything --> DashStats
    Everything --> AdminUsers
Loading
  • * - Administrative access to all endpoints
  • api - Access to api:tokens, api:metrics, etc.
  • ai - Access to ai:alt, ai:tickets, etc.
  • ai:alt - Specific access only to alt-text generation

JWT payload structure includes subject (sub), issued time (iat), optional expiry (exp), and optional token ID (jti) for revocation.

Sources: README.md, bin/jwt.ts

CLI Tool Ecosystem

The platform includes comprehensive CLI tools for development and operations:

  • bun try: Interactive API endpoint testing with auto-generated tokens
  • bun jwt: Complete JWT lifecycle management (create, verify, list, revoke)
  • bun kv: KV storage operations (export, import, list, wipe)
  • bun run test:api: HTTP API integration testing

These tools integrate with the same authentication and validation systems as the web API, ensuring consistency across development workflows.

Sources: bin/try.ts, bin/jwt.ts, bin/kv.ts

Navigation:

Clone this wiki locally