Architecture Overview

Synapse UI is an Nx monorepo that publishes tree-shakable Angular packages under the @synapse-ui npm scope. The library targets enterprise applications that embed generative AI experiences — streaming responses, prompt input, and AI-specific feedback — without coupling to a specific LLM provider.

Design Goals

Provider-agnostic — Components consume generic SSE streams; no Azure/OpenAI SDK in the UI layer.
Performance at stream speed — OnPush change detection and incremental DOM updates for high-frequency SSE chunks.
Themeable by default — All visual values flow through CSS custom properties managed by ThemeService.
Publishable granularity — Secondary entry points (@synapse-ui/ai-prompt, etc.) so consumers import only what they need.
Documented decisions — ADRs capture why, not just what.

High-Level Architecture

flowchart TB
    subgraph Consumer App
        App[Angular Application]
    end

    subgraph Synapse UI Packages
        Theme["@synapse-ui/theme"]
        Prompt["@synapse-ui/ai-prompt"]
        Stream["@synapse-ui/stream-container"]
        Core["@synapse-ui/core"]
    end

    subgraph External
        SSE[SSE Backend]
        Marked[marked]
        Shiki[Shiki]
    end

    App --> Theme
    App --> Prompt
    App --> Stream
    Prompt --> Theme
    Stream --> Theme
    Stream --> Core
    Core --> Marked
    Core --> Shiki
    App -->|EventSource / fetch| SSE
    SSE -->|text/event-stream| Core

Layer Responsibilities

Layer	Package	Responsibility
Theme	`@synapse-ui/theme`	Design tokens, CSS variable maps, `ThemeService`
Core	`@synapse-ui/core`	SSE parsing, stream buffers, shared types and utilities
UI	`@synapse-ui/*`	Standalone Angular components with Storybook stories
Apps	`apps/docs`, `apps/sandbox`	Documentation site and integration reference

Data Flow: Prompt to Streamed Response

sequenceDiagram
    participant User
    participant PromptBar as AiPromptBar
    participant App as Consumer App
    participant Backend as SSE Backend
    participant Container as AiStreamContainer

    User->>PromptBar: Type prompt, press Enter
    PromptBar->>App: submit event (prompt text)
    App->>Backend: POST /chat (opens SSE)
    Backend-->>App: SSE chunks
    App->>Container: append chunks (signal/Observable)
    Container->>Container: Parse markdown (marked)
    Container->>Container: Highlight code (Shiki)
    Container->>User: Rendered streaming output
    User->>PromptBar: Click stop
    PromptBar->>App: stopGeneration event
    App->>Backend: Abort stream

Key Technical Choices

Concern	Choice	Rationale
Monorepo	Nx	Affected builds, generators, consistent tooling
Components	Standalone + OnPush	Modern Angular, performance for streaming
Theming	CSS custom properties	Runtime switching without rebuild
Markdown	marked	Lightweight, extensible
Highlighting	Shiki	Accurate, theme-aware syntax highlighting
Streaming	Generic SSE	Backend-agnostic; works with any compliant server
Docs	Docusaurus + Storybook	Narrative docs + interactive component catalog

See ADRs for full decision records.

MVP Boundary

The minimum viable release includes:

@synapse-ui/theme — ThemeService and token maps
@synapse-ui/ai-prompt — AiPromptBar
@synapse-ui/stream-container — AiStreamContainer

Everything else (skeleton, feedback, button, additional primitives) ships post-MVP.

Design Goals​

High-Level Architecture​

Layer Responsibilities​

Data Flow: Prompt to Streamed Response​

Key Technical Choices​

MVP Boundary​

Related Docs​