Tyto

A full-stack course management and attendance tracking application.

• Backend: Ruby (Roda + Sequel ORM) with Domain-Driven Design architecture
• Frontend: Vue 3 + Vue Router + Element Plus UI
• Build: Webpack
• Auth: Google OAuth with JWT tokens

The backend follows a Domain-Driven Design (DDD) architecture. For architectural details and patterns, see the /ddd-refactoring skill in Claude Code.

Setup

Requirements: Ruby 3.4+, Node.js 20+

1. Install dependencies and copy config templates:

   rake setup

2. Generate JWT key:

   bundle exec rake generate:jwt_key

3. Configure backend_app/config/secrets.yml:

   • JWT_KEY: Paste the generated key from step 2
   • ADMIN_EMAIL: Your Google account email (for admin access)

4. Configure frontend_app/.env.local:

   • VUE_APP_GOOGLE_CLIENT_ID: Google OAuth client ID (see doc/google.md)
   • VUE_APP_GOOGLE_MAP_KEY: Google Maps API key (for location features)

5. Setup databases:

   bundle exec rake db:setup                 # Development database
   RACK_ENV=test bundle exec rake db:setup   # Test database

DevContainer (Optional)

A DevContainer configuration is available for VS Code + Docker users. Open the project in VS Code and select "Reopen in Container" when prompted. The container runs rake setup automatically, then follow steps 2-5 above.

Running Locally

Start both servers in separate terminals:

# Terminal 1: Frontend (webpack dev server with hot reload)
rake run:frontend

# Terminal 2: Backend API server
rake run:api

Important: Open http://localhost:9292 in your browser (the backend port), not 8080. The backend serves both the API and the frontend files from dist/. The webpack dev server on port 8080 only handles compilation.

Testing

The project has three test layers:

Layer	Tool	What it covers	Command
Backend	Minitest	API routes, services, policies, domain	bundle exec rake spec:backend
Frontend	Vitest	Vue components in isolation (jsdom)	bundle exec rake spec:frontend
End-to-end	Playwright	Real browser driving the live app + API	bundle exec rake spec:e2e

bundle exec rake spec            # Backend + frontend (default task) — does NOT run e2e
bundle exec rake spec:backend    # Backend only (Minitest)
bundle exec rake spec:frontend   # Frontend only (Vitest; same as npm test)
bundle exec rake spec:e2e        # Browser end-to-end (Playwright); opt-in, self-contained

Set up the test database before running backend or frontend specs:

RACK_ENV=test bundle exec rake db:setup

spec:e2e is opt-in (not part of rake spec) and manages its own test DB, seed, and frontend build. See Testing Guide for full setup and how the e2e harness works.

Note: the backend suite reports one intentional skip (courses_spec.rb — testing a missing owner role would require deleting seed data the rest of the suite depends on).

Database Commands

bundle exec rake db:migrate     # Run pending migrations
bundle exec rake db:seed        # Seed database with sample data
bundle exec rake db:setup       # Migrate + seed
bundle exec rake db:reset       # Drop + migrate + seed (destructive)
bundle exec rake db:drop        # Delete database (destructive)

Documentation

• Testing Guide — Backend (Minitest), frontend (Vitest), and end-to-end (Playwright) tests
• Google OAuth Setup — Configure Google Cloud credentials
• Heroku Deployment — Deploy to production
• AWS S3 Setup — Configure S3 bucket, IAM, and CORS for file uploads (production)
• S3 Production Smoke Test — One-shot verification after first deploy with S3
• Future Work — Planned improvements and known issues

Key Dependencies

Backend:

• Roda — Routing
• Sequel — Database ORM
• dry-struct — Domain entities
• dry-operation — Railway-oriented services
• Roar — JSON representers

Frontend:

• Vue 3
• Element Plus — UI components
• vue3-google-login — OAuth