Architecture

Technology Stack

Frontend

  • Astro 5 - Static site generation with islands architecture

  • SolidJS - Reactive components for search/filter UI

  • TailwindCSS v4 - Utility-first CSS framework

Backend

  • Astro SSR - Server-side rendering

  • Vercel - Serverless deployment platform

  • Drizzle ORM - Type-safe SQL query builder

Database

  • Turso - Globally distributed SQLite (LibSQL)

  • Edge locations for low-latency reads

Authentication

  • Lucia - Session-based auth library

  • Arctic - OAuth helper for multiple providers

  • Argon2 - Password hashing

Application Flow

graph TB
    subgraph pages [Pages]
        Home[Home Page]
        Browse[Browse Page]
        Submit[Submit Page]
        Auth[Auth Pages]
    end

    subgraph auth [Authentication]
        GitHub[GitHub OAuth]
        GitLab[GitLab OAuth]
        Google[Google OAuth]
        Email[Email/Password]
    end

    subgraph data [Data Layer]
        Drizzle[Drizzle ORM]
        Turso[(Turso DB)]
    end

    Home --> Drizzle
    Browse --> Drizzle
    Submit --> auth
    auth --> Drizzle
    Drizzle --> Turso

Directory Structure

src/
├── components/           # SolidJS components
│   ├── ThemeCard.tsx
│   ├── ThemeGallery.tsx
│   └── SubmitThemeForm.tsx
├── db/
│   ├── index.ts          # Drizzle client
│   └── schema.ts         # Table definitions
├── layouts/
│   └── Layout.astro      # Base layout with nav
├── lib/
│   ├── auth.ts           # Lucia setup
│   ├── password.ts       # Argon2 helpers
│   └── github.ts         # GitHub API helpers
├── pages/
│   ├── index.astro       # Home (featured themes)
│   ├── browse.astro      # Full gallery
│   ├── submit.astro      # Theme submission
│   ├── login.astro
│   ├── register.astro
│   └── api/
│       ├── auth/         # Auth endpoints
│       └── themes/       # Theme API
├── styles/
│   └── global.css        # Tailwind imports
└── types/
    └── theme.ts          # TypeScript types

Request Flow

Page Request

sequenceDiagram
    participant Browser
    participant Vercel
    participant Astro
    participant Turso

    Browser->>Vercel: GET /browse
    Vercel->>Astro: Handle request
    Astro->>Turso: Query themes
    Turso-->>Astro: Theme data
    Astro-->>Vercel: Rendered HTML
    Vercel-->>Browser: Response

Theme Submission

sequenceDiagram
    participant User
    participant App
    participant GitHub
    participant Turso

    User->>App: Submit repo URL
    App->>GitHub: Fetch repo metadata
    GitHub-->>App: Name, stars, etc.
    App->>GitHub: Check preview.png exists
    GitHub-->>App: 200 OK
    App->>Turso: Insert theme (pending)
    Turso-->>App: Success
    App-->>User: Submission confirmed

Key Files

File Purpose

astro.config.mjs

Astro + Vercel adapter config

drizzle.config.ts

Database migration config

src/db/schema.ts

Table definitions (users, sessions, themes)

src/lib/auth.ts

Lucia auth with OAuth providers

src/pages/api/auth/*

OAuth login/callback endpoints

src/pages/api/themes/submit.ts

Theme submission API

Performance Considerations

Home Page

  • Server-renders 6 featured themes

  • No client-side data fetching

  • Minimal JavaScript

Browse Page

  • Full theme list with client-side search/filter

  • SolidJS for reactive UI

  • Hydrates after initial render

Database

  • Turso edge locations minimize latency

  • Simple queries (no joins needed)

  • Read-heavy workload suits SQLite