# 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](../ROADMAP.md).**

---

## 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](./frontend-architecture.md) | Fyrox game plugin, UI system, backend coordination | Partially Implemented |
| [Backend Adapter](./backend-adapter.md) | SDK integration, message transformation, OAuth proxy | Implemented |
| [IPC Protocol](./ipc-protocol.md) | Message types, protocol versioning, bidirectional communication | Implemented |

### Features

| Document | Description | Status |
|----------|-------------|--------|
| [Authentication System](./authentication-system.md) | OAuth flow, API keys, keychain storage | Implemented |
| [Room System](./room-system.md) | Surfaces, MCP tools, image placement, spatial memory | MVP Complete |
| [Animation System](./animation-system.md) | Character states, tool animations, facial expressions | MVP Implemented (placeholder) |
| [Persistence System](./persistence-system.md) | Project files, session logs, crash recovery | MVP Complete |

### Development & Operations

| Document | Description | Status |
|----------|-------------|--------|
| [Debug Server](./debug-server.md) | HTTP API for automated testing | Implemented |
| [Backend Logging](./backend-logging.md) | Structured logging, stdout protection | Implemented |
| [Open Issues](./ISSUES.md) | Known gaps, design questions, action items | Active |

---

## Quick Links

### Getting Started
- **Building the project**: See [CONTRIBUTING.md](../../CONTRIBUTING.md)
- **Project overview**: See [README.md](../../README.md)
- **Development priorities**: See [ROADMAP.md](../ROADMAP.md)
- **AI assistant instructions**: See [CLAUDE.md](../../CLAUDE.md)

### 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](./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](./frontend-architecture.md#4-ui-system-fyrox-ui).

**OAuth Proxy**: For claude.ai authentication, the backend runs a local proxy that injects Bearer tokens. See [authentication-system.md](./authentication-system.md) and [backend-adapter.md](./backend-adapter.md#5-oauth-proxy).

**Room Tools**: The agent interacts with the 3D environment via MCP tools (`create_note`, `look_around`, `examine`). See [room-system.md](./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](./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