# oxide-byte/rust-berlin-leptos architecture

> Architecture diagram of the GitHub repository oxide-byte/rust-berlin-leptos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/oxide-byte/rust-berlin-leptos
- Repository: https://github.com/oxide-byte/rust-berlin-leptos

## Overview

##### Project type and purpose
- This is a full-stack Rust web application that implements the “Rust Hack and Learn” Berlin challenge.
- Frontend: a Leptos (WASM) single-page app styled with Tailwind, compiled and served via Trunk in development, and shipped as static assets in production.
- Backend: an Axum HTTP server (with Tower), exposing a GraphQL API via Juniper, serving both dynamic GraphQL endpoints (query, mutation, subscription) and static assets.
- Database: SurrealDB, accessed from Rust service layers.

##### File structure
- Top-level:
- client/ – Leptos SPA source code
- server/ – Axum GraphQL server, static file host, business logic
- data/ – sample JSON used by file-import service or tests
- docs/ – auto-generated static build of the SPA (for GitHub Pages)
- docker-compose.yaml – multi-container orchestration (likely SurrealDB + server)
- client/:
- src/component – UI components (app shell, tables, modals, clock, navigation)
- src/graphql – auto-generated GraphQL query/mutation/subscription code
- src/model – typed Rust models mirroring GraphQL types
- Trunk.toml, Tailwind config, index.html – front-end build and asset pipeline
- server/:
- src/config – DB connection, environment
- src/graphql – GraphQL schema/domain, resolvers (query, mutation, subscription)
- src/repository – data access for meetup URLs
- src/service – file import, DB initialization, higher-level business logic
- static/ – production-ready built SPA assets

##### Key architecture insights from README
- The acronym SALT: SurrealDB, Axum, Leptos, Tailwind + GraphQL
- Dev flow: `trunk serve` spins up local static server + live-reload frontend; `cargo run` on server starts GraphQL endpoints + static file server.
- Production flow: `trunk build --release` → copy `client/dist` into `server/static`; Axum serves at `/web`, GraphiQL at `/graphiql`, Playground at `/playground`.

a. Main components
1. Frontend (Leptos SPA)
2. GraphQL API server (Axum + Juniper)
3. SurrealDB (persistent data store)
4. (Optional) Developer tooling: Trunk dev server, GraphiQL/Playground UIs
b. Relationships & data flows
- The browser loads the WASM + HTML/CSS from the static assets endpoint on the Axum server (or Trunk dev server).
- The Leptos app issues GraphQL queries/mutations/subscriptions over HTTP/WS to the Axum server.
- Axum’s GraphQL handlers invoke service layer → repository → SurrealDB.
- For subscriptions, Juniper’s subscription resolver pushes updates over WebSockets to the client.
- File-import service reads data.json and seeds SurrealDB on startup (via init_database).
c. Architectural patterns & design principles
- Layered architecture on the server:
- Config → DB connection
- GraphQL resolvers (schema/domain)
- Service layer (business logic)
- Repository (data access)
- Frontend separation:
- Components (UI)
- GraphQL client code (auto-generated)
- Models (typed data)
- Clear boundary between static asset hosting and dynamic GraphQL API within the same server.
d. Key technologies
- Frontend: Leptos (WASM), Thaw (state hydration), Tailwind CSS, Trunk, GraphQL client
- Backend: Rust, Axum, Tower, Juniper-Axum, SurrealDB driver
- Dev/Test: Trunk live-reload, GraphiQL, Playground

## Diagram (Mermaid)

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

    subgraph "Client (Leptos SPA)"
        direction TB
        Entry["main.rs"]:::frontend
        Components["UI Components"]:::frontend
        GQLClient["GraphQL Client Code"]:::frontend
        Models["Typed Models"]:::frontend
        ConfigFiles["Trunk.toml, tailwind.config.js, tailwind.css, index.html"]:::tool
    end

    Browser -->|Loads WASM/HTML/CSS| Entry
    Entry --> Components
    Entry --> GQLClient
    Entry --> Models
    Entry --> ConfigFiles

    %% Server Layer
    subgraph "Server (Axum + Juniper)"
        direction TB
        StaticHost["Static Host"]:::backend
        GraphQLAPI["GraphQL API"]:::backend

        subgraph "GraphQL Layer"
            direction TB
            Query["query.rs"]:::backend
            Mutation["mutation.rs"]:::backend
            Subscription["subscription.rs"]:::backend
            Domain["domain.rs"]:::backend
        end

        subgraph "Service Layer"
            direction TB
            FileImport["file_import.rs"]:::backend
            InitDB["init_database.rs"]:::backend
        end

        Repo["url_repository.rs"]:::backend
    end

    %% Persistence
    DB["SurrealDB"]:::db

    %% External UIs
    GraphiQL["GraphiQL UI"]:::tool
    Playground["Playground UI"]:::tool

    %% Interactions
    Browser -->|GET /web/*| StaticHost
    Browser -->|POST /graphql| GraphQLAPI
    Browser -->|WS /graphql| GraphQLAPI

    GraphiQL -->|POST /graphql| GraphQLAPI
    Playground -->|WS /graphql| GraphQLAPI

    GraphQLAPI -->|"resolve()"| Query
    GraphQLAPI -->|"resolve()"| Mutation
    GraphQLAPI -->|"resolve()"| Subscription
    Domain --> Query
    Domain --> Mutation
    Domain --> Subscription

    Query --> ServiceLayer
    Mutation --> ServiceLayer
    Subscription --> ServiceLayer

    ServiceLayer --> Repo
    FileImport --> InitDB
    InitDB --> DB
    Repo --> DB

    %% Sample Data & Docker
    sampleData["Sample Data (data.json)"]:::tool
    Docker["docker-compose.yaml"]:::tool
    sampleData --> FileImport
    Docker --> DB
    Docker --> StaticHost

    %% GitHub Pages build
    Docs["Auto-generated SPA (docs/)"]:::tool

    %% Click Events
    click Entry "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/client/src/main.rs"
    click Components "https://github.com/oxide-byte/rust-berlin-leptos/tree/master/client/src/component/"
    click GQLClient "https://github.com/oxide-byte/rust-berlin-leptos/tree/master/client/src/graphql/"
    click Models "https://github.com/oxide-byte/rust-berlin-leptos/tree/master/client/src/model/"
    click ConfigFiles "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/client/Trunk.toml"
    click ConfigFiles "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/client/tailwind.config.js"
    click ConfigFiles "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/client/tailwind.css"
    click ConfigFiles "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/client/index.html"
    click sampleData "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/data/data.json"
    click Docker "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/docker-compose.yaml"
    click ServerMain "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/main.rs"
    click DBConfig "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/config/db_connection.rs"
    click Query "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/graphql/query.rs"
    click Mutation "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/graphql/mutation.rs"
    click Subscription "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/graphql/subscription.rs"
    click Domain "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/graphql/domain.rs"
    click Repo "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/repository/url_repository.rs"
    click FileImport "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/service/file_import.rs"
    click InitDB "https://github.com/oxide-byte/rust-berlin-leptos/blob/master/server/src/service/init_database.rs"
    click StaticAssets "https://github.com/oxide-byte/rust-berlin-leptos/tree/master/server/static/"
    click Docs "https://github.com/oxide-byte/rust-berlin-leptos/tree/master/docs/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef db fill:#FFA500,stroke:#000,stroke-width:1px
    classDef tool fill:#D3D3D3,stroke:#000,stroke-width:1px
```
