karashiiro.moe / tiny-workshop
WIP experiment with 95% vibe coding
Star
Fork 0
Watch
tiny-workshop docs design index.md
6.5 kB
Markdown
at main

Tiny Workshop Design Documentation #

Last Updated: 2026-01-11

This directory contains the architectural design documents for Tiny Workshop. These docs describe the intended system design—some parts are implemented, others are planned.

For current development status and priorities, see the ROADMAP.

Architecture Overview #

Tiny Workshop uses a multi-process architecture with two main components:

┌─────────────────────┐         IPC (JSON-RPC)        ┌─────────────────────┐
│   Frontend (Rust)   │ ◄──────────────────────────► │  Backend (TypeScript)│
│      Fyrox 3D       │      stdin/stdout JSON        │    Claude Agent SDK  │
└─────────────────────┘                               └─────────────────────┘
         │                                                      │
         ├─ 3D Rendering (60fps)                               │
         ├─ Chat UI (Fyrox-UI)                                 │
         ├─ Animation System                                    │
         ├─ Room Management                                     ▼
         └─ Persistence                               ┌─────────────────────┐
                                                      │  Claude API / OAuth  │
                                                      └─────────────────────┘

Why two processes?

  • Frontend (Rust/Fyrox): Handles 3D rendering, UI, animations, and state persistence
  • Backend (Bun/TypeScript): Bridges to Claude Agent SDK (TypeScript library)

The IPC boundary allows each component to use the best language for its job while maintaining clean separation of concerns.

Design Documents #

Core Architecture #

Document Description Status
Frontend Architecture Fyrox game plugin, UI system, backend coordination Partially Implemented
Backend Adapter SDK integration, message transformation, OAuth proxy Implemented
IPC Protocol Message types, protocol versioning, bidirectional communication Implemented

Features #

Document Description Status
Authentication System OAuth flow, API keys, keychain storage Implemented
Room System Surfaces, MCP tools, image placement, spatial memory MVP Complete
Animation System Character states, tool animations, facial expressions MVP Implemented (placeholder)
Persistence System Project files, session logs, crash recovery MVP Complete

Development & Operations #

Document Description Status
Debug Server HTTP API for automated testing Implemented
Backend Logging Structured logging, stdout protection Implemented
Open Issues Known gaps, design questions, action items Active

Getting Started #

Key Concepts #

IPC Protocol: All communication between frontend and backend uses JSON lines over stdin/stdout. Each message has a type field for routing. See ipc-protocol.md.

Fyrox-UI: The chat interface uses Fyrox's retained-mode UI system. Widgets are built once and updated via messages. See frontend-architecture.md.

OAuth Proxy: For claude.ai authentication, the backend runs a local proxy that injects Bearer tokens. See authentication-system.md and backend-adapter.md.

Room Tools: The agent interacts with the 3D environment via MCP tools (create_note, look_around, examine). See room-system.md.

Implementation Status Summary #

Component Design Implementation
IPC Protocol ✅ Complete ✅ Complete
Backend Adapter ✅ Complete ✅ Complete (multi-turn via InputGenerator)
Frontend Core ✅ Complete ✅ Complete
Chat UI ✅ Complete ✅ Complete
OAuth Authentication ✅ Complete ✅ Complete
Debug Server ✅ Complete ✅ Complete
Animation System ✅ Complete 🔄 MVP (placeholder cube)
Room System ✅ Complete ✅ MVP Complete
Persistence System ✅ Complete ✅ MVP Complete (room, sessions, resumption)

Design Principles #

  1. Crash Resilience: Frontend must never crash due to backend issues. Use graceful error handling.

  2. Frame Budget: Game loop processes max 10 IPC messages per frame to maintain 60fps.

  3. Memory Budget: Total application <200MB (50MB images, 50MB scene, 30MB code, 70MB overhead).

  4. Stdout is Sacred: Backend must NEVER write to stdout except for IPC JSON messages.

  5. Atomic Writes: Persistence uses temp file + rename pattern to prevent corruption.

  6. Cross-Platform: Support Windows, macOS, and Linux from day one.

Contributing to Design #

When proposing design changes:

  1. Read the relevant existing design doc
  2. Check ISSUES.md for related open questions
  3. Update the design doc with your proposal
  4. Note any implementation impact in the doc's status section
  5. Update this index if adding new documents

Document Conventions #

  • Status field: Each doc has a status in its header (Design, Partially Implemented, Implemented)
  • Rationale sections: Explain why decisions were made, not just what
  • Code examples: Use realistic code that matches actual implementation patterns
  • Open Questions: Each doc may have an "Open Questions" section for unresolved issues
  • Related Documents: Cross-references to other relevant design docs