Skip to main content

Monorepo Structure

Overview​

FAIHT v2 is organized as a monorepo using pnpm workspaces and turbo for build orchestration.

faiht2-mono/
├── apps/
│   ├── web/              # Next.js Frontend (Cloudflare Pages)
│   ├── api/              # Cloudflare Worker (API Gateway)
│   ├── docs-public/      # Public API Documentation (Docusaurus)
│   └── docs-private/     # Internal Wiki (Docusaurus)
├── services/
│   ├── supabase/         # Backend (Edge Functions, Migrations)
│   ├── fetcher/          # Data Fetcher Worker (Docker)
│   └── scheduler/        # Task Scheduler (Docker)
├── packages/
│   ├── core/             # Shared TypeScript types
│   └── assets/           # Shared brand assets (logos, etc.)
├── infra/                # Infrastructure as Code (Terraform, Docker Compose)
└── scripts/              # Utility scripts

Shared Assets​

All applications reference brand assets from a single source:

packages/assets/
└── logo.svg  # Single source of truth

apps/web/public/
└── assets -> ../../../packages/assets  (symlink)

apps/docs-public/static/
└── assets -> ../../../packages/assets  (symlink)

apps/docs-private/static/
└── assets -> ../../../packages/assets  (symlink)

Usage:

  • Web: /assets/logo.svg
  • Docs: assets/logo.svg

OpenAPI Specification​

The API specification is also shared:

openapi.yaml  # Single source of truth (root)

apps/docs-public/api/
└── openapi.yaml -> ../../../openapi.yaml  (symlink)

Docusaurus automatically generates API reference pages from this spec.

Package Dependencies​

Core Types (packages/core)​

Shared TypeScript types used across applications:

  • TrendingHashtag
  • UserProfile
  • Subscription

Apps Dependencies​

  • apps/web → depends on packages/core
  • apps/api → depends on packages/core
  • apps/docs-* → depends on packages/assets (static assets only)

Workspace Commands​

Install Dependencies​

pnpm install

Build All​

pnpm build

Dev Mode (Specific App)​

pnpm --filter web dev
pnpm --filter api dev
pnpm --filter docs-public dev

Run Tests​

pnpm --filter api test

Adding New Packages​

  1. Create directory in packages/
  2. Add package.json with workspace reference:
{
  "name": "@faiht/package-name",
  "version": "0.0.0",
  "private": true
}
  1. Reference in app's package.json:
{
  "dependencies": {
    "@faiht/package-name": "workspace:*"
  }
}

Deployment Pipeline​

Each app/service has its own deployment workflow:

  • Web: Cloudflare Pages (automated on push)
  • API: Cloudflare Workers (automated on push)
  • Docs: Cloudflare Pages (automated on push)
  • Supabase: Supabase CLI (automated on push)
  • Workers: Docker Registry (automated on push)

See Deployment Guide for details.