> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinykit.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> How tinykit works under the hood

## One Server Philosophy

**One server. One deployment. Zero complexity.**

Unlike other platforms where you build locally and deploy separately, tinykit runs the builder AND your app on the same server. Edit at `/tinykit`, ship at `/`.

***

## URL Structure

Your tinykit instance serves everything from a single domain:

```
tinykit Server (Railway)
├── /tinykit/dashboard  → Project list (you)
├── /tinykit/studio     → Edit current domain's app (you)
├── /                   → Your generated app (users)
├── /api/agent          → AI endpoints
├── /api/projects       → Project operations
└── /_pb/_              → PocketBase admin
```

| Path                   | Purpose                     | Who Uses It     |
| ---------------------- | --------------------------- | --------------- |
| `/`                    | Your generated app          | End users       |
| `/tinykit/dashboard`   | List all projects           | You (developer) |
| `/tinykit/studio`      | Edit app for current domain | You (developer) |
| `/tinykit/studio?id=X` | Edit specific project       | You (developer) |
| `/api/agent`           | AI code generation          | Builder         |
| `/_pb/_`               | PocketBase admin            | You (optional)  |

***

## Domain-Based Routing

Run hundreds of apps from one tinykit instance. Each domain serves a different app:

```
calculator.myserver.com/           → Serves calculator app
calculator.myserver.com/tinykit    → Edit calculator app

blog.myserver.com/                 → Serves blog app
blog.myserver.com/tinykit          → Edit blog app

recipes.myserver.com/              → Serves recipes app
recipes.myserver.com/tinykit       → Edit recipes app
```

**How it works:**

1. Point multiple domains to your tinykit server
2. Each domain is associated with a project in PocketBase
3. Root URL (`/`) serves the pre-built HTML for that domain's project
4. `/tinykit` lets you edit the project for the current domain

**Unknown domains** redirect to `/tinykit/new?domain=X` to create a new project.

***

## Tech Stack

<CardGroup cols={2}>
  <Card title="SvelteKit" icon="code">
    Fast, modern framework for the builder and generated apps
  </Card>

  <Card title="CodeMirror 6" icon="pen-to-square">
    Modern code editor with syntax highlighting and autocomplete
  </Card>

  <Card title="OpenAI / Anthropic / Gemini" icon="brain">
    Your choice of AI provider for code generation
  </Card>

  <Card title="PocketBase" icon="database">
    Embedded database for data persistence
  </Card>

  <Card title="Tailwind CSS" icon="palette">
    Utility-first styling for rapid UI development
  </Card>

  <Card title="TypeScript" icon="file-code">
    Type safety throughout the codebase
  </Card>
</CardGroup>

***

## Data Storage

All project data is stored in a single PocketBase collection (`_tk_projects`):

```
_tk_projects
├── frontend_code    → Code (your app's code)
├── content          → Content fields (JSON)
├── design           → CSS variables (JSON)
├── agent_chat       → Conversation history (JSON)
├── snapshots        → Time travel history (JSON)
├── data             → App data collections (JSON)
├── domain           → Associated domain
└── published_html   → Compiled HTML (production build)
```

<Info>
  Everything in one collection means simple backups and easy migrations.
</Info>

***

## Data Flow

<Steps>
  <Step title="You Chat with AI">
    Send a prompt like "Create a todo list app" to the AI Agent panel.
  </Step>

  <Step title="AI Generates Code">
    The AI responds with code, which streams to your browser in real-time.
  </Step>

  <Step title="Files are Saved">
    Generated code is saved to the project's `frontend_code` field.
  </Step>

  <Step title="Preview Updates">
    The live preview compiles and shows your changes immediately.
  </Step>

  <Step title="Build for Production">
    Server compiles Svelte to standalone HTML, saves as static file.
  </Step>

  <Step title="Users See Changes">
    Anyone visiting your root URL sees the updated app instantly.
  </Step>
</Steps>

***

## Build System

**Preview** uses in-browser Svelte compilation for instant feedback.

**Production** uses server-side compilation:

* Svelte 5's native `compile()` function
* Generates standalone HTML with CDN-based imports
* Triggered by clicking "Deploy" button
* Result stored as file attachment in PocketBase

***

## AI Agent System

The AI agent uses a **tool-use pattern** to build your app:

```
You: "Add a contact form"
         │
         ▼
┌─────────────────────────────┐
│  LLM receives:              │
│  - Your prompt              │
│  - Current code       │
│  - Design/content fields    │
│  - Conversation history     │
└─────────────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  LLM calls tools:           │
│  - write_code               │
│  - create_design_field      │
│  - create_content_field     │
│  - create_data_file         │
└─────────────────────────────┘
         │
         ▼
┌─────────────────────────────┐
│  Tools execute              │
│  Results fed back           │
│  Loop until done            │
└─────────────────────────────┘
         │
         ▼
    Response streamed to you
```

### Available Tools

| Tool                   | What It Does                       |
| ---------------------- | ---------------------------------- |
| `write_code`           | Updates app code                   |
| `create_design_field`  | Adds CSS variables (colors, fonts) |
| `create_content_field` | Adds CMS fields (text, images)     |
| `create_data_file`     | Creates data collections           |
| `insert_records`       | Seeds data into collections        |
| `update_spec`          | Updates project metadata           |

***

## Performance

| Operation        | Typical Time              |
| ---------------- | ------------------------- |
| Editor load      | \~100-200ms               |
| File save        | \~50-100ms                |
| Preview refresh  | \~100-200ms               |
| AI response      | \~2-5s (depends on model) |
| Production build | \~500ms-2s                |

***

## Deployment Options

While Railway is recommended for simplicity, you can deploy anywhere that runs Node.js:

<AccordionGroup>
  <Accordion title="Railway (Recommended)">
    One-click deploy with the template. Automatic HTTPS, custom domains, and scaling.

    [![Deploy on Railway](https://railway.app/button.svg)](https://railway.com/deploy/tinykit?referralCode=RCPU7k\&utm_medium=integration\&utm_source=template\&utm_campaign=generic)
  </Accordion>

  <Accordion title="Fly.io">
    ```bash theme={null}
    fly launch
    fly secrets set LLM_API_KEY=sk-...
    fly deploy
    ```
  </Accordion>

  <Accordion title="DigitalOcean App Platform">
    Connect your GitHub repo and configure environment variables in the dashboard.
  </Accordion>

  <Accordion title="Self-hosted VPS">
    ```bash theme={null}
    git clone https://github.com/tinykit-studio/tinykit.git
    cd tinykit
    npm install
    npm run build
    npm run preview
    ```

    Use PM2 or systemd to keep it running.
  </Accordion>

  <Accordion title="Docker">
    ```dockerfile theme={null}
    FROM node:20-alpine
    WORKDIR /app
    COPY . .
    RUN npm install && npm run build
    CMD ["npm", "run", "preview"]
    ```
  </Accordion>
</AccordionGroup>