# cosscom/coss architecture

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

- Interactive diagram: https://gitdiagram.com/cosscom/coss
- Repository: https://github.com/cosscom/coss

## Overview

##### Project Type and Purpose
- This is a multi-app monorepo (“Turborepo”) hosting three Next.js 13 applications—`apps/www`, `apps/ui`, and `apps/origin`—plus shared packages (`packages/ui`, `packages/eslint-config`, `packages/typescript-config`).
- Purpose: Provide the coss.com ecosystem (marketing site, component library & docs, legacy Origin UI), plus a shared UI package and config tooling, all in one codebase.

##### High-Level File Structure Analysis
- Top‐level:
- `apps/`: three Next.js apps
- `packages/`: shared UI components and tooling packages
- Root config: `turbo.json`, `package.json`, TS and lint configs; build scripts use Bun.
- Each Next.js app uses the App Router (`app/` directory), Tailwind CSS, TypeScript, and ships via Vercel.
- `apps/ui/` includes its own content (`.mdx` docs), API route, registry of components & examples, and scripts to generate a registry.
- `apps/origin/` is a legacy, unmaintained snapshot of UI components.

##### README Insights
- The monorepo is orchestrated by Turborepo, building all apps with `bun run build` or individually via filters.
- Env variables link apps to each other at runtime (e.g., `NEXT_PUBLIC_COSS_UI_URL`), enabling navigation between them.
- Licensing is mixed (MIT for `apps/ui` & `apps/origin`; AGPLv3 for the rest).

##### Diagramming the Architecture
a. Main Components
- Developer Workstation
- Monorepo & Build Orchestrator
- Turborepo core
- Bun (build runner)
- Shared Packages
- UI primitives (`packages/ui/src`)
- ESLint & TS config
- Next.js Applications
- `apps/www` (marketing & landing)
- `apps/ui` (component library, docs, API endpoint)
- `apps/origin` (legacy UI snapshot)
- CI/CD & Deployment
- Vercel (or similar)
- Environment variables store
- External Services
- Base UI (underlying primitives)
- Tailwind CSS (styling)
- Third-party APIs: email, SMS, calendar, video, notifications

b. Relationships & Data Flows
- The monorepo root invokes Turborepo/Bun to build or dev-serve each app.
- Each app imports shared code from `packages/ui` and config from `packages/*`.
- During runtime, apps communicate via public URLs configured by environment variables.
- CI/CD pipeline triggers on commits, runs builds/tests, and deploys each app individually to its Vercel project.
- Docs site (`apps/ui`) fetches component metadata (JSON, MDX) from its registry.

c. Architectural Patterns
- Monorepo pattern with Turborepo for caching and parallel builds.
- Multi‐application Next.js (App Router) for each distinct product.
- Shared library package for UI primitives to avoid duplication and enforce consistency.
- FS-based routing and dynamic registration (registry JSON ↔ code generation).

d. Key Technologies
- Next.js 13 App Router
- TypeScript
- Turborepo + Bun
- Tailwind CSS
- Base UI primitives
- Vercel (deployment)
- ESLint & Prettier

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root and Build Orchestrator
    subgraph "Monorepo Root" 
        MR1["turbo.json"]:::config
        MR2["bunfig.toml"]:::config
        MR3["package.json"]:::config
        MR4["prettier.config.mjs"]:::config
        MR5["lint-staged.config.mjs"]:::config
        MR6["bun.lock"]:::config
    end

    Turb["Turborepo Core"]:::build
    Bun["Bun Runner"]:::build

    MR1 --> Turb
    MR2 --> Bun

    %% Shared Packages
    subgraph "Shared Packages" 
        subgraph "packages/ui" 
            UI1["src"]:::code
            UI2["components.json"]:::code
            UI3["package.json"]:::code
        end
        subgraph "packages/eslint-config"
            ESL1["eslint.config.mjs"]:::code
            ESL2["base.js"]:::code
            ESL3["next.js"]:::code
            ESL4["react-internal.js"]:::code
            ESL5["package.json"]:::code
        end
        subgraph "packages/typescript-config"
            TS1["base.json"]:::code
            TS2["nextjs.json"]:::code
            TS3["react-library.json"]:::code
            TS4["package.json"]:::code
        end
    end

    %% Apps
    subgraph "Next.js Applications"
        subgraph "apps/www (Marketing)"
            WWW1["app/"]:::code
            WWW2["next.config.ts"]:::code
            WWW3["postcss.config.mjs"]:::code
            WWW4["tsconfig.json"]:::code
            WWW5["package.json"]:::code
            WWW6["vercel.json"]:::code
        end
        subgraph "apps/ui (Docs & Library)"
            UIAPP1["app/"]:::code
            UIAPP2["app/api/raw/[...slug]/route.ts"]:::code
            UIAPP3["content/docs"]:::code
            UIAPP4["components"]:::code
            UIAPP5["registry"]:::code
            UIAPP6["scripts/build-registry.mts"]:::code
            UIAPP7["scripts/propagate-ui.mts"]:::code
            UIAPP8["next.config.ts"]:::code
            UIAPP9["postcss.config.mjs"]:::code
            UIAPP10["tsconfig.json"]:::code
            UIAPP11["package.json"]:::code
            UIAPP12["vercel.json"]:::code
        end
        subgraph "apps/origin (Legacy)"
            OR1["app/"]:::code
            OR2["components.json"]:::code
            OR3["registry"]:::code
            OR4["public/r"]:::code
            OR5["next.config.ts"]:::code
            OR6["postcss.config.mjs"]:::code
            OR7["tsconfig.json"]:::code
            OR8["package.json"]:::code
            OR9["vercel.json"]:::code
        end
    end

    %% Config & Env
    Env["Environment Variables"]:::config
    subgraph "Root Lint & TS Config"
        RL1[".eslintrc"]:::config
        RL2["tsconfig.json"]:::config
        RL3["tsconfig.scripts.json"]:::config
    end

    %% CI/CD & Deployment
    CI["CI/CD Pipeline"]:::build
    subgraph "Vercel Deployments"
        VWW["www"]:::external
        VUI["ui"]:::external
        VOR["origin"]:::external
    end

    %% External Services
    subgraph "External Services"
        EXT1["Tailwind CSS"]:::external
        EXT2["Base UI Primitives"]:::external
        EXT3["Third-Party APIs"]:::external
    end

    %% Relationships
    Turb -->|builds via| Bun
    Bun -->|"runs builds for"| WWW1 & UIAPP1 & OR1
    UI1 & ESL1 & TS1 -->|"code dependencies"| WWW1 & UIAPP1 & OR1
    EXT2 --> UI1
    EXT1 --> WWW1 & UIAPP1 & OR1
    WWW1 -.->|runtime link| UIAPP1
    UIAPP1 -.->|runtime link| OR1
    CI -->|on commit| Turb
    CI -.->|deploy| VWW & VUI & VOR
    Env --> WWW1 & UIAPP1 & OR1
    EXT3 --> UIAPP2

    %% Click Events
    click MR1 "https://github.com/cosscom/coss/blob/main/turbo.json"
    click MR2 "https://github.com/cosscom/coss/blob/main/bunfig.toml"
    click MR3 "https://github.com/cosscom/coss/blob/main/package.json"
    click MR4 "https://github.com/cosscom/coss/blob/main/prettier.config.mjs"
    click MR5 "https://github.com/cosscom/coss/blob/main/lint-staged.config.mjs"
    click MR6 "https://github.com/cosscom/coss/blob/main/bun.lock"
    click UI1 "https://github.com/cosscom/coss/tree/main/packages/ui/src"
    click UI2 "https://github.com/cosscom/coss/blob/main/packages/ui/components.json"
    click UI3 "https://github.com/cosscom/coss/blob/main/packages/ui/package.json"
    click ESL1 "https://github.com/cosscom/coss/blob/main/packages/eslint-config/eslint.config.mjs"
    click ESL2 "https://github.com/cosscom/coss/blob/main/packages/eslint-config/base.js"
    click ESL3 "https://github.com/cosscom/coss/blob/main/packages/eslint-config/next.js"
    click ESL4 "https://github.com/cosscom/coss/blob/main/packages/eslint-config/react-internal.js"
    click ESL5 "https://github.com/cosscom/coss/blob/main/packages/eslint-config/package.json"
    click TS1 "https://github.com/cosscom/coss/blob/main/packages/typescript-config/base.json"
    click TS2 "https://github.com/cosscom/coss/blob/main/packages/typescript-config/nextjs.json"
    click TS3 "https://github.com/cosscom/coss/blob/main/packages/typescript-config/react-library.json"
    click TS4 "https://github.com/cosscom/coss/blob/main/packages/typescript-config/package.json"
    click WWW1 "https://github.com/cosscom/coss/tree/main/apps/www/app"
    click WWW2 "https://github.com/cosscom/coss/blob/main/apps/www/next.config.ts"
    click WWW3 "https://github.com/cosscom/coss/blob/main/apps/www/postcss.config.mjs"
    click WWW4 "https://github.com/cosscom/coss/blob/main/apps/www/tsconfig.json"
    click WWW5 "https://github.com/cosscom/coss/blob/main/apps/www/package.json"
    click WWW6 "https://github.com/cosscom/coss/blob/main/apps/www/vercel.json"
    click UIAPP1 "https://github.com/cosscom/coss/tree/main/apps/ui/app"
    click UIAPP2 "https://github.com/cosscom/coss/blob/main/apps/ui/app/api/raw/[...slug]/route.ts"
    click UIAPP3 "https://github.com/cosscom/coss/tree/main/apps/ui/content/docs"
    click UIAPP4 "https://github.com/cosscom/coss/tree/main/apps/ui/components"
    click UIAPP5 "https://github.com/cosscom/coss/tree/main/apps/ui/registry"
    click UIAPP6 "https://github.com/cosscom/coss/blob/main/apps/ui/scripts/build-registry.mts"
    click UIAPP7 "https://github.com/cosscom/coss/blob/main/apps/ui/scripts/propagate-ui.mts"
    click UIAPP8 "https://github.com/cosscom/coss/blob/main/apps/ui/next.config.ts"
    click UIAPP9 "https://github.com/cosscom/coss/blob/main/apps/ui/postcss.config.mjs"
    click UIAPP10 "https://github.com/cosscom/coss/blob/main/apps/ui/tsconfig.json"
    click UIAPP11 "https://github.com/cosscom/coss/blob/main/apps/ui/package.json"
    click UIAPP12 "https://github.com/cosscom/coss/blob/main/apps/ui/vercel.json"
    click OR1 "https://github.com/cosscom/coss/tree/main/apps/origin/app"
    click OR2 "https://github.com/cosscom/coss/blob/main/apps/origin/components.json"
    click OR3 "https://github.com/cosscom/coss/tree/main/apps/origin/registry"
    click OR4 "https://github.com/cosscom/coss/tree/main/apps/origin/public/r"
    click OR5 "https://github.com/cosscom/coss/blob/main/apps/origin/next.config.ts"
    click OR6 "https://github.com/cosscom/coss/blob/main/apps/origin/postcss.config.mjs"
    click OR7 "https://github.com/cosscom/coss/blob/main/apps/origin/tsconfig.json"
    click OR8 "https://github.com/cosscom/coss/blob/main/apps/origin/package.json"
    click OR9 "https://github.com/cosscom/coss/blob/main/apps/origin/vercel.json"
    click RL1 "https://github.com/cosscom/coss/blob/main/.eslintrc"
    click RL2 "https://github.com/cosscom/coss/blob/main/tsconfig.json"
    click RL3 "https://github.com/cosscom/coss/blob/main/tsconfig.scripts.json"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#73B1FF
    classDef build fill:#D7F5D7,stroke:#6BC36B
    classDef external fill:#FFE8B7,stroke:#FFC85C
    classDef config fill:#E0E0E0,stroke:#A0A0A0
```
