Skip to main content

Monorepo Structure

Synapse UI uses an Nx workspace with npm as the package manager. Projects are organized into apps (runnable targets) and libs (publishable or shared code).

Directory Layout​

synapse-ui/
├── apps/
│   ├── docs/                      # Docusaurus documentation site
│   │   ├── docs/                  # Docusaurus-side nav (may symlink to /docs)
│   │   ├── docusaurus.config.ts
│   │   └── sidebars.ts
│   └── sandbox/                   # Reference Angular app for integration testing
│       └── src/
├── libs/
│   ├── core/                      # @synapse-ui/core (internal/shared utilities)
│   │   └── src/
│   │       ├── lib/
│   │       │   ├── sse/           # SSE parser, EventSource wrapper
│   │       │   └── markdown/      # Chunk buffer, stream helpers
│   │       └── index.ts
│   ├── theme/                     # @synapse-ui/theme
│   │   └── src/
│   │       ├── lib/
│   │       │   ├── tokens/        # Token definitions (TS + CSS)
│   │       │   └── theme.service.ts
│   │       └── index.ts
│   └── ui/
│       ├── ai-prompt/             # @synapse-ui/ai-prompt
│       ├── stream-container/      # @synapse-ui/stream-container
│       ├── button/                # @synapse-ui/button (post-MVP)
│       ├── generative-skeleton/     # @synapse-ui/generative-skeleton (post-MVP)
│       └── feedback/              # @synapse-ui/feedback (post-MVP)
├── docs/                            # Canonical markdown documentation (this folder)
├── tools/
│   └── generators/                  # Custom Nx schematics (future)
├── nx.json
├── package.json
├── tsconfig.base.json               # Path aliases for @synapse-ui/*
└── README.md

Nx Project Tags​

Use tags to enforce module boundaries via ESLint:

TagProjectsCan import from
type:appdocs, sandboxtype:lib
type:libAll libstype:lib (theme, core only where needed)
scope:themetheme—
scope:corecorescope:theme
scope:uiui/*scope:theme, scope:core

Path Aliases​

tsconfig.base.json maps import paths:

{
  "paths": {
    "@synapse-ui/theme": ["libs/theme/src/index.ts"],
    "@synapse-ui/core": ["libs/core/src/index.ts"],
    "@synapse-ui/ai-prompt": ["libs/ui/ai-prompt/src/index.ts"],
    "@synapse-ui/stream-container": ["libs/ui/stream-container/src/index.ts"]
  }
}

Publishable Libraries​

Each UI component is a secondary entry point built with ng-packagr into Angular Package Format (APF):

dist/libs/ui/
├── ai-prompt/
│   ├── fesm2022/
│   ├── package.json
│   └── index.d.ts
└── stream-container/
    └── ...

Consumers install individual packages:

npm install @synapse-ui/theme @synapse-ui/ai-prompt @synapse-ui/stream-container

Apps​

apps/docs — Docusaurus​

  • Hosts the public documentation website.
  • Ingests markdown from /docs at build time.
  • Deployed separately from npm packages.

apps/sandbox — Integration App​

  • Minimal Angular app demonstrating MVP flow.
  • Target for Cypress E2E tests.
  • Not published to npm.

Build Graph​

Nx computes a dependency graph. Typical build order:

theme → core → ui/ai-prompt
             → ui/stream-container
             → sandbox (depends on ui libs)

Use affected commands in CI:

nx affected -t lint,test,build