# ghostwriternr/nightona architecture

> Architecture diagram of the GitHub repository ghostwriternr/nightona, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ghostwriternr/nightona
- Repository: https://github.com/ghostwriternr/nightona

## Overview

##### Project type and purpose
- This is a full-stack, self-hosted development environment (“Nightona”) that combines:
- A React+TypeScript SPA (frontend) for chat-driven coding and live preview
- A Cloudflare Worker (backend) to orchestrate AI code generation, snapshot management, and sandboxed Vite servers
- Integration with external services (Daytona for sandboxes, Anthropic/Claude for AI)

##### File structure
- Top-level:
- Dockerfile, wrangler.jsonc – deployment configs
- scripts/ – one-time setup (create-snapshot.ts)
- worker/ – backend code handling AI requests and sandbox management
- src/ – React frontend (components/ui, hooks, assets)
- public/, index.html – static assets & entry point
- Configuration: tsconfig.*, vite.config.ts, eslint.config.js
- External-service keys passed via .dev.vars or Wrangler secrets

##### Extract architectural insights from README
- Frontend communicates with Worker API over HTTP
- Worker calls Claude Code CLI & Daytona API to create/modify sandboxed dev environments
- Each sandbox runs a Vite dev server serving the live preview
- Conversation state is preserved across requests

##### Main components
A. User’s Browser (React SPA)
B. Cloudflare Worker API
C. Claude Code CLI (invoked by the Worker)
D. Daytona Service (external cloud sandbox provider)
E. Sandboxed Environment (Vite dev server + project files)
F. Anthropic/Claude API (AI model)
G. Persistence (session context store, if any)

##### Relationships and data flows
1. User sends a “chat instruction” from the React UI → Worker’s `/api/chat` endpoint
2. Worker → Anthropic/Claude API to generate or modify code
3. Worker → Claude Code CLI (local snapshot) to apply changes to the sandbox project files
4. Worker → Daytona API to spin up or update a sandboxed Vite instance with the latest code
5. Sandboxed Vite server pushes code changes to the React UI live preview (WebSocket or HMR)
6. Worker returns updated conversation/context state back to the UI

##### Architectural patterns and design principles
- Client–server separation (React SPA vs. Worker API)
- Micro-backend using serverless functions (Cloudflare Worker)
- Externalized stateful sandbox orchestration (Daytona)
- Continuous HMR/live-preview loop for rapid feedback
- Modular UI design with shadcn/ui component library

##### Relevant technologies to annotate
- React, TypeScript, Tailwind CSS, shadcn/ui (frontend)
- Vite Dev Server (sandboxed preview)
- Cloudflare Workers + Wrangler (backend)
- Claude Code CLI (local code engine)
- Daytona API (sandbox orchestration)
- Anthropic / Claude API (LLM)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["React SPA"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Worker["Cloudflare Worker API"]:::backend
        SandboxMgr["Sandbox Manager"]:::backend
        Types["Type Definitions"]:::backend
        WranglerCfg["Deployment Config"]:::backend
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        ClaudeCLI["Claude Code CLI"]:::processing
        AnthropicAPI["Anthropic / Claude API"]:::external
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        Daytona["Daytona Service"]:::infra
        Sandbox["Sandboxed Vite Server"]:::infra
    end

    %% Relationships
    Browser -->|POST /api/chat| Worker
    Worker -->|call Claude API| AnthropicAPI
    Worker -->|invoke CLI| ClaudeCLI
    Worker -->|orchestrate sandbox| Daytona
    Daytona -->|provision| Sandbox
    Sandbox -->|HMR update| Browser
    Worker -->|return context| Browser

    %% Click Events
    click Browser "https://github.com/ghostwriternr/nightona/blob/main/src/main.tsx"
    click Worker "https://github.com/ghostwriternr/nightona/blob/main/worker/index.ts"
    click SandboxMgr "https://github.com/ghostwriternr/nightona/blob/main/worker/sandbox-manager.ts"
    click Types "https://github.com/ghostwriternr/nightona/blob/main/worker-configuration.d.ts"
    click WranglerCfg "https://github.com/ghostwriternr/nightona/blob/main/wrangler.jsonc"
    click ClaudeCLI "https://github.com/ghostwriternr/nightona/blob/main/scripts/create-snapshot.ts"
    click AnthropicAPI "https://github.com/ghostwriternr/nightona/blob/main/worker/index.ts"
    click Daytona "https://github.com/ghostwriternr/nightona/blob/main/docs/daytona.txt"
    click Sandbox "https://github.com/ghostwriternr/nightona/blob/main/vite.config.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef backend fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef processing fill:#FFF3E0,stroke:#E65100,color:#EF6C00
    classDef external fill:#FFEBEE,stroke:#B71C1C,color:#C62828
    classDef infra fill:#EDE7F6,stroke:#4A148C,color:#6A1B9A
```
