# max-legrand/espejo architecture

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

- Interactive diagram: https://gitdiagram.com/max-legrand/espejo
- Repository: https://github.com/max-legrand/espejo

## Overview

##### Project Type and Purpose
- Espejo is a full-stack application combining a Zig‐based backend (located in the src directory) with a Svelte/Vite-powered frontend (in the web directory).
- Its primary purpose is to enable shared file storage and clipboard operations over a local network (and via the internet when hosted), with live updates via websockets.
- The README confirms that it can run in Docker (via provided docker-compose files) or as a standalone binary.

##### File Structure for Architectural Clues
- Top-Level Separation:
– Backend: The src folder (with files like main.zig, shutdown.zig, state.zig, ws.zig, wslog.zig) indicates the core Zig application logic, including state management and websocket handling.
– Frontend: The web folder contains all front‑end code (Svelte components, configuration files such as svelte.config.js, vite.config.ts, and package.json). It also shows a build process that outputs static files in web/dist.
- Infrastructure/Deployment:
– Docker-related files (dockerfile, docker-compose.yml, docker-compose-local.yml) suggest containerization and simplified deployment.
– Build scripts and configuration files (build.zig and build.zig.zon) imply a managed Zig build process.
- Distribution:
– The prod folder (with prod/dist and the wasm file) indicates production assets and build artifacts.

##### Extract Key Concepts from the README
- The README emphasizes the use of websockets for live streaming, explaining that the backend is responsible for state synchronization.
- It outlines steps for both building and running the application, highlighting that the frontend and backend are built separately.
- Authentication options (via environment variables) hint at middleware or gateway logic on the backend to validate and control access when the application is exposed to the Internet.

a. Main Components:
- Client Browser(s): Running the Svelte-based frontend.
- Frontend Static Site/Assets: Served from the web/dist folder, generated by Vite and Svelte.
- Zig-Based Backend Server: Hosting the application logic, managing state, handling websockets, and performing file storage/clipboard synchronization.
- Websocket Communication Channel: Representing the real-time bidirectional connection between the client and the backend.
- Optional: Authentication Middleware/Service (applied in production based on environment variables).
- Deployment Infrastructure: Docker containers defined by docker-compose files and potentially separate containers/services for frontend and backend.

b. Relationships and Interactions:
- The client browser loads the static assets (HTML, CSS, and JS) from the frontend server.
- Once loaded, the client establishes a websocket connection with the backend for live updates.
- The backend, implemented in Zig, handles file storage, maintains shared state, and broadcasts live changes via websockets to all connected clients.
- The docker-compose setup can be shown as a container orchestration layer managing both the backend and (if applicable) the frontend components.
- If authentication is enabled (via environment variables), it should be depicted as an intercepting service or middleware layer on the backend that secures requests.

c. Architectural Patterns and Principles:
- Separation of Concerns: Clear split between a client-side UI (Svelte) and a backend that handles application logic and data synchronization.
- Event-Driven/Real-Time Communication: Using websockets to push updates across clients.
- Containerization: Deployment via Docker provides isolation and ease of scaling or managing different services.

d. Important Technologies, Frameworks, and Libraries:
- Zig: For the backend logic, websocket handling, and state management.
- Svelte & Vite: For building the front-end user interface.
- Docker: For containerizing the application with docker-compose defining service relationships.
- PNPM: For managing frontend dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CB["Client Browser"]:::client
    FE["Frontend (Svelte/Vite)"]:::frontend
    WS["WebSocket Client (JS)"]:::ws
    Auth["Authentication Middleware (Optional)"]:::auth
    BE["Backend (Zig Websocket Server)"]:::backend

    subgraph "Deployment Infrastructure"
        Docker["Docker Compose"]:::infra
        Build["Build & Distribution"]:::infra
    end

    CB -->|"HTTP"| FE
    CB -->|"WebSocket"| WS
    WS -->|"connects"| Auth
    Auth -->|"validates"| BE
    BE -->|"broadcasts_updates"| CB

    Docker --> FE
    Docker --> Auth
    Docker --> BE
    Build --> FE
    Build --> BE

    click BE "https://github.com/max-legrand/espejo/blob/main/src/main.zig"
    click BE "https://github.com/max-legrand/espejo/blob/main/src/state.zig"
    click BE "https://github.com/max-legrand/espejo/blob/main/src/ws.zig"
    click BE "https://github.com/max-legrand/espejo/blob/main/src/wslog.zig"
    
    click FE "https://github.com/max-legrand/espejo/tree/main/web/dist"
    click FE "https://github.com/max-legrand/espejo/blob/main/web/src/App.svelte"
    
    click WS "https://github.com/max-legrand/espejo/blob/main/web/src/lib/ws.ts"
    
    click Docker "https://github.com/max-legrand/espejo/blob/main/docker-compose.yml"
    click Docker "https://github.com/max-legrand/espejo/blob/main/docker-compose-local.yml"
    click Docker "https://github.com/max-legrand/espejo/tree/main/dockerfile"
    
    click Build "https://github.com/max-legrand/espejo/blob/main/build.zig"
    click Build "https://github.com/max-legrand/espejo/blob/main/build.zig.zon"
    click Build "https://github.com/max-legrand/espejo/tree/main/prod/dist"
    click Build "https://github.com/max-legrand/espejo/tree/main/prod/dist/espejo"
    click Build "https://github.com/max-legrand/espejo/tree/main/prod/dist/scratchpad"
    click Build "https://github.com/max-legrand/espejo/blob/main/prod/dist/wasm.wasm"

    classDef client fill:#E0F7FA,stroke:#00796B,stroke-width:2px;
    classDef frontend fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef ws fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef auth fill:#FFCDD2,stroke:#E64A19,stroke-width:2px;
    classDef backend fill:#D1C4E9,stroke:#7B1FA2,stroke-width:2px;
    classDef infra fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
```
