# mrbacony/analog-tools architecture

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

- Interactive diagram: https://gitdiagram.com/mrbacony/analog-tools
- Repository: https://github.com/mrbacony/analog-tools

## Overview

##### Project Type and Purpose
- This is an Nx monorepo (“AnalogTools”) that contains:
- A full-stack example app (`apps/analog-example`) built on AnalogJS (Angular SSR + Vite) with both REST (v1) and tRPC endpoints.
- Two reusable libraries under `packages/`:
– `@analog-tools/auth`: OAuth flows, route guards, session middleware
– `@analog-tools/session`: Pluggable session store layer (Redis, Unstorage)
- A Docker folder provisioning a Keycloak realm for OAuth.
- GitHub CI/CD workflows for testing and releases.

##### File Structure and Architectural Insights
- Top-level Nx workspace orchestrates builds, linting, tests, and deployments.
- `apps/analog-example/` splits into:
- **Frontend**: Angular components, pages, Tailwind/CSS, Vite dev/server entry (`main.ts`)
- **Backend**: Node SSR entry (`main.server.ts`), Express-style middleware + routes under `src/server`, tRPC routers.
- `packages/auth` and `packages/session` are built via Rollup/Vite, then imported by the example app and potentially by other AnalogJS projects.
- Docker Compose runs Keycloak as the external identity provider; the session store package expects configurable backends (Redis, etc.).

##### Key Components & Relationships
A. **Monorepo (Nx) Orchestration**
– Manages tasks: `nx serve analog-example`, `nx build`
– Defines project boundaries, dependencies, and versioning for `apps/` and `packages/`.
B. **Example App**
– **Client (Browser)**
- Angular + AnalogJS renders pages, consumes APIs via tRPC client or REST fetches.
- Auth redirects to Keycloak for login, receives callback, obtains tokens.
– **Server (Node)**
- Serves SSR pages; exposes API layers:
· tRPC endpoint (`/api/trpc/[trpc]`)
· REST endpoint (`/api/v1/hello`, etc.)
- Applies middleware: session loader (`useAnalogAuthMiddleware`), route protection.
- Delegates to auth/session libraries for OAuth logic and session persistence.
C. **Auth & Session Libraries**
– Imported by the app’s server code.
– Perform OAuth token exchange with Keycloak, create/manage session objects, store in Redis or Unstorage.
D. **External Services**
– **Keycloak (Docker)**: OAuth authorization server.
– **Redis** (not shown in Docker Compose but supported by session package).
E. **CI/CD**
– GitHub Actions pipelines: unit tests, lint, release publishing.

##### Architectural Patterns & Design Principles
- Monorepo & shared-library pattern (Nx)
- Full-stack meta-framework (AnalogJS) combining SSR + client hydration
- API layering: tRPC for type-safe RPC, REST for legacy or simple endpoints
- Middleware pipeline for auth/session
- Pluggable persistence via abstract store interfaces in session library

##### Final Recommendations
- Be exhaustive in labeling every API surface and middleware stage without cluttering—use callouts or legends where needed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Dev Tools
    subgraph "Dev Tools"
        direction TB
        NxMonorepo["Nx Monorepo Orchestration"]:::codeModule
        CI["CI/CD Pipelines"]:::pipeline
    end

    %% Libraries
    subgraph "Shared Libraries"
        direction TB
        AuthLib["@analog-tools/auth"]:::codeModule
        SessionLib["@analog-tools/session"]:::codeModule
    end

    %% Example App
    subgraph "Example App (apps/analog-example)" 
        direction TB
        subgraph "Frontend (Browser)"
            direction TB
            Browser["Angular + AnalogJS Client"]:::codeModule
        end
        subgraph "Backend (Node SSR & APIs)"
            direction TB
            SSR["Node SSR (main.server.ts)"]:::codeModule
            RESTAPI["REST API (/api/v1/hello)"]:::codeModule
            TRPCAPI["tRPC API (/api/trpc/[trpc])"]:::codeModule
            Middleware["Auth Middleware"]:::codeModule
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Keycloak["Keycloak (Docker)"]:::external
        Redis["Redis Store"]:::dataStore
    end

    %% Runtime Flows
    Browser -->|"HTTP Request"| SSR
    SSR -->|"renders SSR pages"| Browser
    Browser -->|"HTTP GET /api/v1/hello"| RESTAPI
    Browser -->|"tRPC call"| TRPCAPI

    SSR -->|"useAnalogAuthMiddleware"| AuthLib
    SSR -->|"session operations"| SessionLib
    RESTAPI -->|"apply middleware"| Middleware
    TRPCAPI -->|"apply middleware"| Middleware

    AuthLib -->|"OAuth token exchange"| Keycloak
    Keycloak -->|"tokens"| AuthLib
    SessionLib -->|"store/retrieve session"| Redis

    %% Build & CI Dependencies
    NxMonorepo -.->|builds| AuthLib
    NxMonorepo -.->|builds| SessionLib
    NxMonorepo -.->|serves| Browser
    NxMonorepo -.->|serves| SSR
    CI -.->|runs tests & releases| NxMonorepo

    %% Click Events - Dev Tools
    click NxMonorepo "https://github.com/mrbacony/analog-tools/blob/main/nx.json"
    click NxMonorepo "https://github.com/mrbacony/analog-tools/blob/main/project.json"
    click NxMonorepo "https://github.com/mrbacony/analog-tools/blob/main/tsconfig.base.json"
    click CI "https://github.com/mrbacony/analog-tools/blob/main/ .github/workflows/ci.yml"
    click CI "https://github.com/mrbacony/analog-tools/blob/main/ .github/workflows/release.yml"

    %% Click Events - Example App Frontend
    click Browser "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/main.ts"
    click Browser "https://github.com/mrbacony/analog-tools/tree/main/apps/analog-example/src/app/**"
    click Browser "https://github.com/mrbacony/analog-tools/tree/main/apps/analog-example/src/app/pages/**"
    click Browser "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/index.html"
    click Browser "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/styles.css"
    click Browser "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/vite.config.ts"

    %% Click Events - Example App Backend
    click SSR "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/main.server.ts"
    click Middleware "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/server/middleware/auth.ts"
    click RESTAPI "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/server/routes/api/v1/hello.ts"
    click TRPCAPI "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/server/routes/api/trpc/[trpc].ts"
    click TRPCAPI "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/server/trpc/trpc.ts"
    click TRPCAPI "https://github.com/mrbacony/analog-tools/blob/main/apps/analog-example/src/server/trpc/context.ts"
    click TRPCAPI "https://github.com/mrbacony/analog-tools/tree/main/apps/analog-example/src/server/trpc/routers/**"

    %% Click Events - Auth Library
    click AuthLib "https://github.com/mrbacony/analog-tools/blob/main/packages/auth/src/index.ts"
    click AuthLib "https://github.com/mrbacony/analog-tools/blob/main/packages/auth/src/functions/useAnalogAuth.ts"
    click AuthLib "https://github.com/mrbacony/analog-tools/blob/main/packages/auth/src/functions/useAnalogAuthMiddleware.ts"
    click AuthLib "https://github.com/mrbacony/analog-tools/tree/main/packages/auth/src/routes/**"
    click AuthLib "https://github.com/mrbacony/analog-tools/blob/main/packages/auth/src/services/oauth-authentication.service.ts"
    click AuthLib "https://github.com/mrbacony/analog-tools/blob/main/packages/auth/src/services/session.service.ts"

    %% Click Events - Session Library
    click SessionLib "https://github.com/mrbacony/analog-tools/blob/main/packages/session/src/core/session.ts"
    click SessionLib "https://github.com/mrbacony/analog-tools/blob/main/packages/session/src/core/session-functions.ts"
    click SessionLib "https://github.com/mrbacony/analog-tools/blob/main/packages/session/src/core/use-session.ts"
    click SessionLib "https://github.com/mrbacony/analog-tools/blob/main/packages/session/src/stores/redis-session-store.ts"
    click SessionLib "https://github.com/mrbacony/analog-tools/blob/main/packages/session/src/stores/unstorage-session-store.ts"

    %% Click Events - Docker
    click Keycloak "https://github.com/mrbacony/analog-tools/blob/main/docker/docker-compose.yml"
    click Keycloak "https://github.com/mrbacony/analog-tools/blob/main/docker/keycloak/imports/realm-config.json"

    %% Styles
    classDef codeModule fill:#E0F7FA,stroke:#0288D1,stroke-width:1px
    classDef dataStore fill:#C8E6C9,stroke:#388E3C,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#F57C00,stroke-width:1px
    classDef pipeline stroke-dasharray: 5 5,stroke:#757575,fill:none
```
