# o2sdev/openselfservice architecture

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

- Interactive diagram: https://gitdiagram.com/o2sdev/openselfservice
- Repository: https://github.com/o2sdev/openselfservice

## Overview

##### Project type and purpose
- This is a full-stack, monorepo-based open-source framework (“Open Self Service”) for building composable customer portals.
- It uses Turborepo to orchestrate multiple “apps” (a Next.js frontend, a NestJS API Harmonization Server, a docs site) together with internal packages (UI library, framework core, integrations, blocks, utilities, CLI).

##### File structure
- Top-level “apps” directory:
- apps/frontend – Next.js frontend starter
- apps/api-harmonization – NestJS integration/orchestration layer
- apps/docs – Docusaurus docs site
- Top-level “packages” directory with:
- ui – shadcn/ui-based component library
- framework – NestJS base modules, controllers, interceptors, SDK generator templates
- integrations – adapters for Strapi CMS, Redis, Algolia, Medusa, Zendesk, “mocked”
- blocks – composable content/page feature packages, each with API, frontend, SDK sub-projects
- modules, utils, telemetry, configs, CLI (create-o2s-app)
- Root contains tooling and config for Turborepo, Docker, Husky, linting, GitHub Actions, Vercel.

##### README for additional insights
- Describes key features: composability, API-agnostic integration, Next.js starter, NestJS harmonization server, TypeScript SDK, pre-built integrations.
- Emphasizes a decoupled architecture: frontend ←→ harmonization server ←→ external headless services.

##### Components
a. Main components
- Frontend App (Next.js)
- API Harmonization Server (NestJS)
- Internal packages:
- UI library
- Framework core
- Blocks & Modules
- Integrations (Strapi, Redis, Algolia, Medusa, Zendesk, Mocked)
- CLI / Generators
- Utilities & SDK
- External services:
- Strapi CMS
- Redis Cache
- Algolia Search
- Medusa Commerce
- Zendesk Tickets
- Other headless APIs (SurveyJS, CRM, ERP)
- CI/CD & Deployment:
- GitHub Actions Workflows
- Docker Compose (dev)
- Vercel (frontend)

b. Relationships & interactions
- Frontend ←(HTTP/REST or GraphQL calls via SDK)→ API Harmonization Server
- Server modules use Integration Adapters to fetch/normalize data from external services, applying caching via Redis.
- Frontend consumes UI library, Blocks SDK, and TypeScript SDK from monorepo packages.
- Developers scaffold new blocks/integrations via CLI, code generation templates in Turbo.
- CI/CD pipelines build & test apps and packages, then deploy frontend to Vercel and backend containers to Docker or other cloud.

c. Architectural patterns & principles
- Monorepo with Turborepo: fast incremental builds, cross-package caching.
- Modular NestJS micro-architecture: each domain (articles, orders, tickets…) is a self-contained module.
- Composable/Plugin pattern: blocks & integrations are independently developed sub-packages.
- API-agnostic harmonization layer: loose coupling via adapter interfaces.
- Shared design system: component library (ui) used across frontend & storybook.

d. Key technologies & frameworks
- Next.js, React, shadcn/ui, Tailwind CSS
- NestJS, TypeScript, Node.js
- Turborepo (monorepo management)
- GitHub Actions, Docker, Vercel
- External headless APIs: Strapi, Redis, Algolia, Medusa, Zendesk.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo Apps"
        FE["Next.js Frontend"]:::app
        API["NestJS Harmonization API"]:::app
        DOCS["Docusaurus Docs Site"]:::app
    end

    subgraph "Internal Packages"
        UI["UI Library"]:::package
        FRAMEWORK["Framework Core"]:::package
        BLOCKS["Blocks"]:::package
        MODULES["Modules"]:::package

        subgraph "Integrations"
            STRAPI_ADPT["Strapi CMS Adapter"]:::package
            ALG_ADPT["Algolia Search Adapter"]:::package
            MEDUSA_ADPT["Medusa Commerce Adapter"]:::package
            REDIS_ADPT["Redis Cache Adapter"]:::package
            ZENDESK_ADPT["Zendesk Tickets Adapter"]:::package
            MOCKED_ADPT["Mocked Adapter"]:::package
        end

        CLI["CLI / Generators"]:::package
        TURBO_GEN["Turbo Generator Templates"]:::package
        UTIL_API["Utils & SDK - API Harmonization"]:::package
        UTIL_FE["Utils & SDK - Frontend"]:::package
        UTIL_LOG["Utils & SDK - Logger"]:::package
        TELEMETRY["Telemetry"]:::package
    end

    subgraph "External Services"
        Strapi["Strapi CMS"]:::external
        Redis["Redis Cache"]:::external
        Algolia["Algolia Search"]:::external
        Medusa["Medusa Commerce"]:::external
        Zendesk["Zendesk Tickets"]:::external
        OtherAPIs["Other Headless APIs"]:::external
    end

    subgraph "CI/CD & Deployment"
        GHA["GitHub Actions"]:::infra
        DOCKER["Docker Compose (dev)"]:::infra
        VERCEL["Vercel Deployment"]:::infra
        TURBO_CONF["Turborepo Config"]:::infra
    end

    FE -->|uses| UI
    FE -->|uses| BLOCKS
    FE -->|uses| UTIL_FE
    FE -->|HTTP/GraphQL| API

    API -->|core modules| FRAMEWORK
    API -->|self-contained modules| MODULES
    API -->|helpers| UTIL_API
    API -->|logging| UTIL_LOG
    API -->|telemetry| TELEMETRY

    API -->|calls| STRAPI_ADPT
    API -->|calls| ALG_ADPT
    API -->|calls| MEDUSA_ADPT
    API -->|calls| REDIS_ADPT
    API -->|calls| ZENDESK_ADPT
    API -->|calls| MOCKED_ADPT

    STRAPI_ADPT -->|connects to| Strapi
    REDIS_ADPT -->|connects to| Redis
    ALG_ADPT -->|connects to| Algolia
    MEDUSA_ADPT -->|connects to| Medusa
    ZENDESK_ADPT -->|connects to| Zendesk
    MOCKED_ADPT -->|connects to| OtherAPIs

    GHA -->|builds & tests| FE
    GHA -->|builds & tests| API
    GHA -->|builds & tests| DOCS
    GHA -->|builds & tests| UI
    GHA -->|builds & tests| FRAMEWORK

    DOCKER -->|runs| API
    VERCEL -->|deploys| FE
    TURBO_CONF -->|orchestrates| FE
    TURBO_CONF -->|orchestrates| API
    TURBO_CONF -->|orchestrates| DOCS

    click FE "https://github.com/o2sdev/openselfservice/tree/main/apps/frontend"
    click API "https://github.com/o2sdev/openselfservice/tree/main/apps/api-harmonization"
    click DOCS "https://github.com/o2sdev/openselfservice/tree/main/apps/docs"
    click UI "https://github.com/o2sdev/openselfservice/tree/main/packages/ui"
    click FRAMEWORK "https://github.com/o2sdev/openselfservice/tree/main/packages/framework"
    click BLOCKS "https://github.com/o2sdev/openselfservice/tree/main/packages/blocks"
    click MODULES "https://github.com/o2sdev/openselfservice/tree/main/packages/modules"
    click STRAPI_ADPT "https://github.com/o2sdev/openselfservice/tree/main/packages/integrations/strapi-cms"
    click ALG_ADPT "https://github.com/o2sdev/openselfservice/tree/main/packages/integrations/algolia"
    click MEDUSA_ADPT "https://github.com/o2sdev/openselfservice/tree/main/packages/integrations/medusajs"
    click REDIS_ADPT "https://github.com/o2sdev/openselfservice/tree/main/packages/integrations/redis"
    click ZENDESK_ADPT "https://github.com/o2sdev/openselfservice/tree/main/packages/integrations/zendesk"
    click MOCKED_ADPT "https://github.com/o2sdev/openselfservice/tree/main/packages/integrations/mocked"
    click CLI "https://github.com/o2sdev/openselfservice/tree/main/packages/cli/create-o2s-app"
    click TURBO_GEN "https://github.com/o2sdev/openselfservice/tree/main/turbo/generators"
    click UTIL_API "https://github.com/o2sdev/openselfservice/tree/main/packages/utils/api-harmonization"
    click UTIL_FE "https://github.com/o2sdev/openselfservice/tree/main/packages/utils/frontend"
    click UTIL_LOG "https://github.com/o2sdev/openselfservice/tree/main/packages/utils/logger"
    click TELEMETRY "https://github.com/o2sdev/openselfservice/tree/main/packages/telemetry"
    click GHA "https://github.com/o2sdev/openselfservice/tree/main/.github/workflows"
    click DOCKER "https://github.com/o2sdev/openselfservice/blob/main/docker-compose.yml"
    click VERCEL "https://github.com/o2sdev/openselfservice/blob/main/vercel.json"
    click TURBO_CONF "https://github.com/o2sdev/openselfservice/blob/main/turbo.json"

    classDef app fill:#cce5ff,stroke:#004085;
    classDef package fill:#d4edda,stroke:#155724;
    classDef external fill:#fff3cd,stroke:#856404,stroke-dasharray:5 5;
    classDef infra fill:#e2e3e5,stroke:#6c757d;
```
