# xmlking/spectacular architecture

> Architecture diagram of the GitHub repository xmlking/spectacular, 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/xmlking/spectacular
- Repository: https://github.com/xmlking/spectacular

## Overview

##### Main Components

- Monorepo Structure (Turborepo): Place an overarching “Monorepo” container that includes all apps and shared packages.
- Applications:
– Console: A SvelteKit-based portal (apps/console) that appears to be a core admin/dashboard app.
– Web: A public-facing website (apps/web), built in SvelteKit and Astro components.
– Smart: Another SvelteKit application focusing on “smart” or AI-assisted features.
– Docs: A documentation site (apps/docs) built with Astro.
- Shared Packages:
– UI Library: (packages/ui) containing components, themes, and utilities.
– Typescript and Utils: (packages/typescript-config, packages/utils) for shared configurations and helper functions.
- Backend & Services:
– API endpoints nested under routes (e.g. apps/console/src/routes/api).
– Serverless functions under the functions folder.
– GraphQL & Hasura/Nhost integration (the “nhost” folder holds metadata, migrations, seeds, and email templates).
- Third-Party & External Services:
– Authentication services (Auth.js and nhost-auth).
– GraphQL services via Houdini.
– Email services handled by Nhost.
– Testing tools (vitest for unit tests, playwright for end-to-end tests).
– Deployment tooling (Docker, CI/CD configs in .github folder, and Turborepo’s build and release scripts).

##### Relationships and Interactions

- Monorepo (Turborepo) at the top as a container that orchestrates multiple apps and shared libraries.
- API layer: within apps/console (and similar apps) the routes (especially those in “api”) interact with external GraphQL and backend services (Hasura, nhost).
- That deployment and build processes are managed centrally via Turborepo scripts and CI/CD workflows (shown in the .github, Dockerfile, and turborepo config files).
- External integrations:
– Authentication services connect to the apps via Auth.js/nhost.
– The GraphQL layer (Houdini) enables communication between the frontend and Hasura databases.
– Testing frameworks feed back into CI pipelines.

##### Architectural Patterns and Design Principles

- Modularized Design: Multiple SvelteKit apps interacting through shared libraries (UI, utils, types, etc.) within the monorepo.
- Separation of Concerns: The division between frontend (SvelteKit apps, Astro for docs) and backend (serverless functions, GraphQL APIs, authentication).
- Microservice Elements: Even though the project is monolithic in repository structure, the use of functions and separate API routes suggest a service-oriented approach.
- CI/CD and Automated Testing: Emphasize that a robust pipeline exists (with GitHub workflows, linting, formatting tests, E2E tests) which is an integral part of the system.

##### Specific Technologies and Relationships

- SvelteKit as the primary framework for “Console”, “Smart”, and “Web” apps.
- Astro used for “Docs”.
- Tailwind CSS and supported UI libraries (SkeletonUI, Shadcn, Flowbite) in shared UI components.
- Houdini (GraphQL client) and Hasura for the data layer.
- Docker and serverless deployment configurations.
- CI/CD workflows (GitHub actions, Turborepo build commands) that unify the deployment process.
- Authentication provided by Auth.js and nhost.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Container
    A["Monorepo (Turborepo)"]:::monorepo

    %% Applications Subgraph
    subgraph "Applications"
        A1["Console App (SvelteKit)"]:::app
        A2["Web App (SvelteKit/Astro)"]:::app
        A3["Smart App (SvelteKit)"]:::app
        A4["Docs App (Astro)"]:::app
    end

    %% Shared Packages Subgraph
    subgraph "Shared Packages"
        P1["UI Library"]:::package
        P2["TS Config"]:::package
        P3["Utils Library"]:::package
    end

    %% Backend & Integrations Subgraph
    subgraph "Backend & Integrations"
        B1["API Endpoints"]:::backend
        B2["Serverless Functions"]:::backend
        B3["GraphQL & Hasura Integration"]:::backend
        B4["Authentication Integration"]:::backend
    end

    %% CI/CD & Deployment Subgraph
    subgraph "CI/CD & Deployment"
        C1["CI/CD Workflows"]:::cicd
        C2["Docker Config"]:::cicd
    end

    %% Connections from Monorepo to Major Layers
    A ---> A1
    A ---> A2
    A ---> A3
    A ---> A4
    A ---> P1
    A ---> P2
    A ---> P3
    A ---> B1
    A ---> B2
    A ---> B3
    A ---> B4
    A ---> C1
    A ---> C2

    %% Application specific interactions
    A1 -->|"apiCall"| B1
    A1 -->|"authCall"| B4
    B1 ---|"triggers"| B2
    B1 -->|"fetchData"| B3

    %% All Apps using Shared Packages
    A1 -->|"uses"| P1
    A2 -->|"uses"| P1
    A3 -->|"uses"| P1
    A4 -->|"uses"| P1

    A1 -->|"uses"| P2
    A2 -->|"uses"| P2
    A3 -->|"uses"| P2
    A4 -->|"uses"| P2

    A1 -->|"uses"| P3
    A2 -->|"uses"| P3
    A3 -->|"uses"| P3
    A4 -->|"uses"| P3

    %% CI/CD flows connecting to deployments (implied)
    C1 -->|"build_and_test"| A1
    C1 -->|"build_and_test"| A2
    C1 -->|"build_and_test"| A3
    C1 -->|"build_and_test"| A4
    C1 -->|"deploys"| B1
    C1 -->|"deploys"| B2
    C1 -->|"deploys"| B3
    C1 -->|"deploys"| B4
    C2 -->|"containerizes"| A1
    C2 -->|"containerizes"| A2
    C2 -->|"containerizes"| A3
    C2 -->|"containerizes"| A4

    %% Click Events
    click A "https://github.com/xmlking/spectacular/blob/main/turbo.json"
    click A1 "https://github.com/xmlking/spectacular/tree/main/apps/console"
    click A2 "https://github.com/xmlking/spectacular/tree/main/apps/web"
    click A3 "https://github.com/xmlking/spectacular/tree/main/apps/smart"
    click A4 "https://github.com/xmlking/spectacular/tree/main/apps/docs"
    click P1 "https://github.com/xmlking/spectacular/tree/main/packages/ui"
    click P2 "https://github.com/xmlking/spectacular/tree/main/packages/typescript-config"
    click P3 "https://github.com/xmlking/spectacular/tree/main/packages/utils"
    click B1 "https://github.com/xmlking/spectacular/tree/main/apps/console/src/routes/api"
    click B2 "https://github.com/xmlking/spectacular/tree/main/functions"
    click B3 "https://github.com/xmlking/spectacular/tree/main/nhost"
    click B3 "https://github.com/xmlking/spectacular/blob/main/apps/console/houdini.config.js"
    click B3 "https://github.com/xmlking/spectacular/blob/main/apps/console/schema.graphql"
    click B4 "https://github.com/xmlking/spectacular/blob/main/apps/console/src/lib/server/hooks/auth.ts"
    click C1 "https://github.com/xmlking/spectacular/blob/main/.github"
    click C2 "https://github.com/xmlking/spectacular/tree/main/Dockerfile"
    click C2 "https://github.com/xmlking/spectacular/blob/main/.dockerignore"

    %% Styles
    classDef monorepo fill:#a8dadc,stroke:#1d3557,stroke-width:2px;
    classDef app fill:#f4a261,stroke:#e76f51,stroke-width:2px;
    classDef package fill:#e9c46a,stroke:#264653,stroke-width:2px;
    classDef backend fill:#2a9d8f,stroke:#264653,stroke-width:2px,fill-opacity:0.6;
    classDef cicd fill:#e76f51,stroke:#264653,stroke-width:2px,fill-opacity:0.7;
```
