Platerator

An actuator plate configurator exploring web → parametric CAD → quote pipelines.

Prerequisites

• Rust (latest stable)
• Bun (JavaScript runtime)
• Just (command runner) - install via cargo install just or brew install just
• Terraform (IaC)
• AWS CLI (Cloud provider)

Quick Start

# Install frontend dependencies
cd frontend && bun install && cd ..

# Start development servers
just dev

This starts:

• API: http://localhost:3030 (Rust/Axum)
• Frontend: http://localhost:3000 (Bun/React with HMR)

Project Structure

├── crates/           # Rust workspace (see crates/README.md)
│   ├── domain/       # Core types (ActuatorPlate, Millimeters)
│   ├── validation/   # Business logic (no_std, field validators)
│   ├── web/          # Axum REST API server
│   └── parametric/   # KCL parametric CAD definitions
├── frontend/         # React SPA (Bun, TailwindCSS, shadcn/ui)
└── justfile          # Dev and build commands

See crates/README.md for detailed crate documentation.

Architecture

Development: Two servers - Bun (frontend with HMR) + Rust (API)

Production: One server - Rust serves API + static frontend

┌─────────────────────────────────────────┐
│            Production Server            │
│                                         │
│   /api/*  →  Axum handlers              │
│   /*      →  Static files (React SPA)   │
│                                         │
└─────────────────────────────────────────┘

Development Commands

Just (Project Orchestration)

just dev            # Start both servers for development
just dev-frontend   # Start only frontend dev server
just build-release  # Build frontend + Rust for production
just test           # Run all tests once
just clean          # Clean build artifacts
just                # List all available commands

Bacon (Interactive Rust Development)

bacon run-long   # Run API with auto-restart on file changes
bacon test       # Run tests with auto-rerun on changes
bacon clippy     # Run linting with auto-rerun on changes
bacon check      # Run type checking with auto-rerun

Workflow Patterns

Full-stack development:

just dev

Backend-focused development (two terminals):

# Terminal 1
bacon run-long

# Terminal 2
cd frontend && bun dev

Frontend-only:

just dev-frontend
# or
cd frontend && bun dev

Quick test run:

just test

Test-driven development:

bacon test

AWS Deployment (Docker-Free!)

Platerator deploys to AWS Lightsail with no Docker required:

# One-time setup (~5 min)
just tf-init       # Initialize Terraform
just tf-plan       # Review infrastructure (13 resources, ~$5/month)
just tf-apply      # Create AWS infrastructure
just set-zoo-token # Store zoo CLI token

# Deploy application
git push origin master  # Triggers GitHub Actions build
just deploy             # Download + deploy to Lightsail

How it works: GitHub Actions builds the Linux binary, you download it and deploy to Lightsail using your local AWS credentials. No Docker on your machine, no container overhead in production.

See QUICKSTART.md for step-by-step guide.

Infrastructure: Lightsail ($3.50/mo), S3, DynamoDB, Secrets Manager, CloudWatch

API Documentation

Interactive API Documentation

Platerator includes interactive OpenAPI (Swagger) documentation:

Development: http://localhost:3030/api/docs Production: https://your-domain.com/api/docs

The Swagger UI provides:

• Complete API endpoint documentation
• Request/response schemas with examples
• Interactive "Try it out" functionality
• Parameter descriptions and validation rules

API Endpoints

Method	Path	Description
GET	/api/health	Health check
POST	/api/validate	Validate plate parameters without generating files
POST	/api/generate	Generate STEP and glTF model files
GET	/api/download/step/{session_id}	Download generated STEP file
GET	/api/download/gltf/{session_id}	Download generated glTF file
GET	/api/docs	Interactive Swagger UI documentation
GET	/api/openapi.json	OpenAPI specification (JSON)

Documentation

Development

• CLAUDE.md - Development guide (architecture, patterns, workflows)
• crates/README.md - Rust crates documentation
• frontend/README.md - Frontend documentation
• TESTING.md - Testing documentation

Deployment

• QUICKSTART.md - Start here for AWS deployment
• DEPLOYMENT.md - Complete deployment guide
• terraform/README.md - Infrastructure documentation

Planning

• PLAN.md - Feature roadmap
• LEARNING.md - Technical exploration notes