How o2sdev/openselfservice works
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.