Project Architecture

Understand the structure and technical stack of stevenson.space

Learn about the architecture, directory structure, and build process of stevenson.space.

Tech Stack

stevenson.space is built with modern web technologies:

Frontend Framework

• Vue 3 - Progressive JavaScript framework with Composition API
• TypeScript - Type-safe JavaScript for better developer experience
• Pinia - Official state management library for Vue 3
• Vue Router - Official routing library for Vue 3

Build Tools

• Vite - Next-generation frontend build tool
• Sass - CSS preprocessor for advanced styling
• ESLint - Code linting with Airbnb style guide
• Prettier - Code formatting

UI & Animation

• FontAwesome - Icon library
• GSAP - Animation library
• Anime.js - JavaScript animation engine
• Howler.js - Audio library

Infrastructure

• Cloudflare Pages - Static site hosting with global CDN
• Cloudflare Workers - Serverless backend for Jukebox and email forms
• Google OAuth 2.0 - Authentication
• Sentry - Error tracking and monitoring

Project Structure

The source code is organized into the following directories:

src/
├── App.vue                 # Root Vue component
├── main.ts                 # Application entry point
├── shims-vue.d.ts         # TypeScript declarations for Vue
├── assets/                # Static assets (images, fonts, etc.)
│   ├── links/            # Link-related assets
│   └── occasions/        # Special occasion assets
├── components/            # Reusable Vue components
│   └── cards/            # Card component variants
├── data/                  # Static data and configurations
├── router/                # Vue Router configuration
├── stores/                # Pinia state management stores
├── styles/                # Global styles and SCSS files
├── themes/                # Theme configurations and assets
│   ├── assets/           # Theme-specific assets
│   │   ├── header-images/
│   │   └── particles/    # Particle effects (candy, fall, halloween, etc.)
│   └── base/             # Base theme configurations
├── utils/                 # Utility functions and helpers
└── views/                 # Page-level Vue components
    ├── Home/
    ├── Calendar/
    ├── Bell Schedules/
    ├── Settings/
    ├── Jukebox/
    ├── GpaCalculator/
    └── ... (20+ views)

Key Directories

src/views/

Page-level components representing different routes. Each view directory contains:

• Main Vue component(s) for that page
• Page-specific styles and logic

Examples: Home, Calendar, Bell Schedules, Settings, Jukebox, QRCodes, Documents

src/components/

Reusable UI components used across multiple views:

• Card.vue - Base card component
• CardContainer.vue - Container for card layouts
• Checkbox.vue - Custom checkbox component
• ColorPicker.vue - Color selection component
• CustomLink.vue - Enhanced link component
• ConfirmPopup.vue - Confirmation dialog
• And many more…

Components include Storybook stories (.stories.ts) for documentation and testing.

src/stores/

Pinia stores for state management:

• authentication.ts - User authentication state
• clock.ts - Clock and time-related state
• schedules.ts - Bell schedule data and logic
• themes.ts - Theme selection and customization
• user-settings.ts - User preferences and settings

src/themes/

Theme system with seasonal and holiday themes:

• Base theme configurations
• Header images for different themes
• Particle effects (candy, fall, halloween, sakura, st-patricks)

src/router/

Vue Router configuration defining:

• Route paths and components
• Navigation guards
• Route-level code splitting

Build Process

The build process is orchestrated by Vite and npm scripts:

1. Prebuild: Data scraping

   npm run prebuild
   

   Runs scrapers/events.js to fetch and update event data before building.

2. Build: Vite compilation

   npm run build
   

   Vite compiles TypeScript, bundles JavaScript, processes Vue components, and optimizes assets for production.

3. Deploy: Cloudflare Pages

   The built files are deployed to Cloudflare Pages, which provides:

   • Global CDN distribution
   • Automatic HTTPS
   • Preview deployments for pull requests

Vite Configuration

Key configuration from vite.config.js:

// Path aliases for cleaner imports
resolve: {
  alias: {
    '@': path.resolve(__dirname, './src'),
  },
}

// Development server settings
server: {
  port: 8080,
  allowedHosts: ['localhost', '*.pages.dev', 'stevenson.space']
}

The @ alias allows imports like import Component from '@/components/Component.vue' instead of relative paths.

Testing Infrastructure

The project uses:

• Vitest - Unit testing framework
• Storybook - Component development and visual testing
• Playwright - Browser automation for component tests

Storybook

# Run Storybook dev server
npm run storybook

# Build static Storybook
npm run build-storybook

Backend Services

stevenson.space uses Cloudflare Workers for serverless backend functionality:

• Music Backend: Jukebox music storage and streaming
• Email Forms: Contact and notification forms

The music backend can be run locally:

npm run music-dev

Code Organization Principles

1. Component-based architecture: UI is broken into small, reusable components
2. Type safety: TypeScript ensures type correctness across the codebase
3. Centralized state: Pinia stores manage shared application state
4. Theme system: Modular theme architecture supports easy customization
5. Path aliases: Clean imports using @/ prefix

The codebase contains over 10,000 lines of code. Take time to explore and understand the architecture before making changes.

Next Steps

• Review the contribution guidelines for coding standards
• Explore individual components in Storybook
• Check the Pinia stores to understand application state