Skip to main content
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
# 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

Build docs developers (and LLMs) love

Get started for freeTalk to us