# spartan-ng/spartan architecture

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

- Interactive diagram: https://gitdiagram.com/spartan-ng/spartan
- Repository: https://github.com/spartan-ng/spartan

## Overview

##### Project type and purpose
- This is an Nx-based monorepo hosting two major concerns:
- spartan/ui – an Angular UI library of un-styled “brain” primitives plus styled “helm” components (in `libs/brain` and `libs/ui`).
- spartan/stack – a full-stack example app (in `apps/app`) built with AnalogJS (Nitro server), Angular, Tailwind, tRPC, Drizzle ORM and Supabase.
- In addition there is an Nx-CLI plugin (`libs/cli`), tooling for docs/release (`libs/tools`), Storybook & E2E test apps (`apps/ui-storybook-e2e`, `apps/trpc-app-e2e`), and CI/CD pipeline definitions under `.github/workflows`.

##### File structure
- Top-level “apps” folder for runnable projects:
- `app` – the example full-stack Angular/Analog application
- `ui-storybook-e2e` – Cypress tests against Storybook
- `trpc-app-e2e` – end-to-end tests for the tRPC API
- “libs” folder for shareable code:
- `libs/brain` – un-styled Angular CDK–based primitives
- `libs/ui` – “helm” libraries that layer styling on top of brain primitives
- `libs/cli` – an Nx plugin / Angular CLI extension to scaffold spartan/ui into a workspace
- `libs/tools` – custom executors & generators for docs and release automation
- `libs/trpc` – shared tRPC client/server utilities
- Configuration and scripts: Nx workspace files (`nx.json`, `project.json`), GitHub workflows, Storybook configs, Jest and Cypress configs, Drizzle migrations under `apps/app/drizzle`.

##### README for additional insights
- The README clearly states two focal points:
a. “spartan/ui” – port of shadcn/ui to Angular, built as paired brain/helm libs
b. “spartan/stack” – an example full-stack application demonstrating Supabase, Drizzle, Analog, tRPC, Angular, Tailwind, Nx
- Storybook is the primary development environment for UI primitives.
- E2E tests run against Storybook and the example app.
- CI workflows automate testing, releases, nightly builds.

##### Final advice
- Essential architectural boundaries: front end vs server vs data vs packages vs CI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Apps
    subgraph "Apps" 
        direction TB
        Frontend["Frontend App\n(Angular + AnalogJS + Tailwind)"]:::frontend
        Backend["Backend Server\n(AnalogJS/Nitro + tRPC)"]:::frontend
    end

    %% Infrastructure
    DB["Supabase Postgres\n(Drizzle ORM)"]:::infra

    %% Libraries
    subgraph "Libraries"
        direction TB
        Brain["UI Brain Primitives"]:::lib
        Helm["UI Helm Styled Components"]:::lib
        CLI["CLI Plugin"]:::lib
        Tools["Tools Library"]:::lib
    end

    %% Testing
    subgraph "Testing Environments"
        direction TB
        Storybook["Storybook E2E"]:::test
        TRPC_E2E["tRPC API E2E"]:::test
    end

    %% CI/CD
    CICD["CI/CD Workflows"]:::cicd

    %% Relationships
    Frontend -->|imports| Brain
    Frontend -->|imports| Helm
    Frontend -->|"calls tRPC (HTTP)"| Backend
    Backend -->|"executes ORM"| DB
    Helm -->|depends on| Brain
    Storybook -->|loads stories from| Helm
    Storybook -->|Cypress tests| Frontend
    TRPC_E2E -->|tests API| Backend
    CLI -->|scaffolds projects| Frontend
    Tools -->|provides executors| CICD
    CICD -->|runs tests| Storybook
    CICD -->|runs tests| TRPC_E2E
    CICD -->|builds & releases| Frontend
    CICD -->|builds & releases| Helm

    %% Click Events
    click Frontend "https://github.com/spartan-ng/spartan/tree/main/apps/app"
    click Backend "https://github.com/spartan-ng/spartan/tree/main/apps/app/src/server"
    click DB "https://github.com/spartan-ng/spartan/tree/main/apps/app/drizzle"
    click Brain "https://github.com/spartan-ng/spartan/tree/main/libs/brain"
    click Helm "https://github.com/spartan-ng/spartan/tree/main/libs/ui"
    click CLI "https://github.com/spartan-ng/spartan/tree/main/libs/cli"
    click Tools "https://github.com/spartan-ng/spartan/tree/main/libs/tools"
    click Storybook "https://github.com/spartan-ng/spartan/tree/main/apps/ui-storybook-e2e"
    click TRPC_E2E "https://github.com/spartan-ng/spartan/tree/main/apps/trpc-app-e2e"
    click CICD "https://github.com/spartan-ng/spartan/tree/main/.github/workflows"

    %% Styles
    classDef frontend fill:#D6E5FF,stroke:#007BFF,color:#000;
    classDef infra fill:#D6FFD6,stroke:#28A745,color:#000;
    classDef lib fill:#FFE5B4,stroke:#FF8C00,color:#000;
    classDef test fill:#E5D6FF,stroke:#6F42C1,color:#000;
    classDef cicd fill:#F0F0F0,stroke:#6C757D,color:#000;
```
