How cosscom/coss works
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