Skip to content

CLAUDE.md

Latest commit

 

History

History
212 lines (170 loc) · 7.05 KB

CLAUDE.md

File metadata and controls

212 lines (170 loc) · 7.05 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Frontier Forge is a streamlined voting platform for the Frontier Tower community to propose and prioritize building improvements. Ideas flow through submission → voting → approval → external tracking. Discussion happens in Telegram, project tracking happens in GitHub/Linear.

Development Commands

Core Development

npm run dev          # Start development server (http://localhost:5173)
npm run build        # Build for production
npm run preview      # Preview production build
npm run check        # Type-check and validate Svelte components
npm run check:watch  # Type-check in watch mode

Database Operations

npm run db:generate  # Generate Prisma client after schema changes
npm run db:push      # Push schema to database (no migrations)
npm run db:studio    # Open Prisma Studio GUI for database management
npm run db:seed      # Seed database with test data (when implemented)

Architecture & Core Patterns

Tech Stack

  • SvelteKit 5 with Svelte runes ($state, $derived, $effect) for reactivity
  • Prisma ORM with PostgreSQL hosted on Supabase (shared pooler, no IPv4 addon)
  • SSE (Server-Sent Events) via sveltekit-sse for real-time updates
  • Frontier Tower OAuth for authentication (JWT sessions)
  • Frontier Tower Design System - Modern Professional Elegance with comprehensive component library

Svelte 5 Runes Pattern

// State management with runes
let ideas = $state([]);                    // Reactive state
let filtered = $derived(ideas.filter(...)); // Computed values
$effect(() => { /* side effects */ });      // React to changes

SSE Real-Time Architecture

The platform uses Server-Sent Events for one-way server→client updates:

  1. Server Broadcasting (/api/sse/+server.ts): Maintains connections and emits events
  2. Event Types: new_idea, vote_update, idea_status_change
  3. Client Store (sse-updates.svelte.ts): Manages SSE connection and distributes updates
  4. Broadcaster Utility (sse-broadcaster.ts): Triggers broadcasts after database changes

Flow: Database change → sseBroadcaster.broadcast*() → SSE endpoint → Connected clients

Database Schema Key Concepts

Idea Lifecycle States:

  • OPEN → Active for voting
  • APPROVED → Approved for implementation
  • PROJECT → Implementation started (tracked externally)
  • ARCHIVED → Completed or rejected

Authentication Flow

  1. User clicks sign in → Redirects to /auth/login
  2. OAuth with Frontier Tower (test mode: code=test-code)
  3. Callback creates JWT token via jose library
  4. Token stored in httpOnly session cookie
  5. getUserFromSession() validates on each request

Key Implementation Patterns

Form Actions (SvelteKit Way)

// +page.server.ts
export const actions = {
  default: async ({ request, cookies }) => {
    const user = await getUserFromSession(cookies);
    // Process form data
    return { success: true };
  }
};

Optimistic UI Updates

The VoteButton component demonstrates optimistic updates:

  1. Update UI immediately
  2. Send request to server
  3. Revert if request fails
  4. Broadcast SSE update on success

Server-Side Data Loading

// +page.server.ts
export const load: PageServerLoad = async () => {
  const ideas = await prisma.idea.findMany({
    include: { votes: true, submitter: true }
  });
  return { ideas };
};

Current Implementation Status

✅ Completed

  • Homepage feed with Rising/Forged filters
  • Idea submission form
  • Upvoting with optimistic updates
  • Top 5 ideas view (formerly assembly)
  • SSE real-time updates for votes and new ideas
  • JWT authentication with Frontier Tower OAuth
  • Tailwind CSS styling with custom design system
  • Simplified project model with external tracking links

🚧 Needs Implementation

  • Idea detail pages (/idea/[id]) - simplified without comments
  • User profiles
  • Email notifications via Resend
  • Search and filtering
  • Admin approval workflow

Environment Configuration

Required environment variables (see .env.example):

  • DATABASE_URL - Supabase PostgreSQL with pooler
  • DIRECT_URL - Direct connection for migrations
  • JWT_SECRET - At least 32 characters for session tokens
  • FRONTIER_* - OAuth credentials (test mode available)
  • RESEND_API_KEY - Email service (optional for now)

Known Requirements & Constraints

  • Node.js 20.19+ required (SvelteKit 5 dependency)
  • No migrations: Uses db:push for schema changes
  • SSE Limitations: In-memory connection storage (needs Redis for multi-instance)
  • Test Auth: Use code=test-code for development OAuth flow

Design System

Frontier Forge uses the Frontier Tower Design System implementing Modern Professional Elegance:

4-Level Surface Hierarchy

--surface-0: Background level (subtle warmth)
--surface-1: Cards, modals (elevated white)  
--surface-2: Hover states (cooler contrast)
--surface-3: Active elements (highest contrast)

Component Classes

/* Buttons */
.btn-primary    # Frontier purple, primary actions
.btn-secondary  # Neutral, secondary actions  
.btn-destructive # Red, dangerous actions
.btn-ghost      # Transparent, subtle actions

/* Cards */
.card           # Standard elevation
.card-elevated  # Higher elevation for modals
.card-modal     # Highest elevation for overlays

/* Status Indicators */
.status-success   # Green for positive states
.status-warning   # Orange for warnings
.status-error     # Red for errors
.status-info      # Blue for informational

/* Form Elements */
.input            # Standard input styling
.input-error      # Error state styling
.textarea         # Multi-line input
.label            # Form labels
.label-required   # Required field indicator (adds red *)

Color Palette

  • Primary: Frontier purple (#6B46C1) for brand elements
  • Success: Green for positive actions and states
  • Warning: Orange for cautions and warnings
  • Destructive: Red for errors and dangerous actions
  • Info: Blue for informational elements

Dark Mode Support

The design system automatically adapts to dark mode via CSS custom properties and prefers-color-scheme.

Adding New Features

To add a new SSE event:

  1. Add event type to IdeaUpdate interface
  2. Create broadcast method in sse-broadcaster.ts
  3. Call broadcaster after database operation
  4. Handle event in client subscription

Simplified Architecture Notes:

  • Comments removed - discussion happens in Telegram
  • Assembly model removed - just shows top 5 voted ideas
  • Project tracking simplified - just links to external tools
  • Focus on core voting and prioritization functionality

To add a new page:

  1. Create route folder in src/routes/
  2. Add +page.svelte for UI
  3. Add +page.server.ts for data loading/actions
  4. Use getUserFromSession() for protected routes

To modify database schema:

  1. Update prisma/schema.prisma
  2. Run npm run db:push
  3. Run npm run db:generate
  4. Update affected server-side code