# duyet/monorepo architecture

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

- Interactive diagram: https://gitdiagram.com/duyet/monorepo
- Repository: https://github.com/duyet/monorepo

## Overview

##### Project type and purpose
- This is a Turborepo-powered monorepo hosting five Next.js front-ends (“home”, “blog”, “insights”, “cv”, “photos”), plus shared code under `packages/*`.
- Each “app” is a Next.js project using React, TypeScript, Tailwind, and leverages Next’s file-based routing for pages and API routes (e.g., `ping/route.ts`, `robots.txt/route.ts`, `rss.xml/route.ts`).
- Shared code (UI components, business-logic utilities, TS interfaces, ESLint/Prettier/Tailwind configs) lives under `packages/*`.
- CI/CD is configured via GitHub Actions (lint/test, OAuth, deploy pipelines) and Husky hooks on commit.

##### High-level architecture
- Monorepo Root:
- `turbo.json`, `package.json`, top-level TS/Prettier/Eslint configs coordinate builds and workspace resolution.
- Husky (pre-commit, commit-msg) ensures code quality.
- GitHub Actions run workflows: lint/test (`eslint.yml`, `test.yml`), code-review bots, OAuth, and deployment.
- Apps:
- Each `apps/<name>` folder is a separate Next.js application that depends on shared packages (`packages/components`, `packages/libs`, `packages/interfaces`, etc.).
- They produce static and server-side-rendered pages, plus simple API endpoints under `app/<...>/route.ts`.
- Environment variables (.env.*) configure production vs. staging.
- Packages:
- `components`: shared React UI components and design tokens.
- `libs`: shared business-logic helpers (fetchers, markdown parser, URL utilities).
- `interfaces`: shared TS types (Cloudflare, GitHub, Post, etc.).
- Config packages (ESLint, Prettier, Tailwind, TSConfig) centralize styling and typing rules.
- External Services:
- Cloudflare APIs (for blog analytics, KV, Pages deployments), PostHog (blog analytics), ClickHouse (insights data), WakaTime (developer metrics), Unsplash (photos), etc.
- Deployment:
- Each app is built via `turbo run build --filter=apps/<name>`, then deployed to Cloudflare Pages (or GitHub Pages) as static or SSR.
- CDN edges serve global traffic.

##### Essential details to capture
- Monorepo structure and workspace resolution.
- Turborepo’s role in orchestrating parallel builds and caching.
- Shared packages injection into apps.
- Next.js runtime (pages + API routes).
- CI/CD flows from commit to production.
- External data and analytics dependencies.
- Multi-app deployments to Cloudflare Pages/CDN.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Monorepo Root
  subgraph "Monorepo Root"
    direction TB
    turbojson["turbo.json"]:::code
    pkgjson["package.json"]:::code
    tsconfig["tsconfig.json"]:::code
    prettierignore[".prettierignore"]:::code
    commitlint[".commitlintrc.js"]:::code
  end

  %% CI/CD Pipeline
  subgraph "CI/CD Pipeline" 
    direction TB
    ghactions["GitHub Actions"]:::ci
    husky["Husky Hooks"]:::ci
    subgraph "Workflows"
      eslintwf["eslint.yml"]:::ci
      testwf["test.yml"]:::ci
      oauthwf["claude-oauth.yml"]:::ci
      reviewwf["claude-code-review.yml"]:::ci
    end
    subgraph "Husky Hooks"
      precommit["pre-commit"]:::ci
      commitmsg["commit-msg"]:::ci
    end
  end

  %% Build Orchestrator
  subgraph "Build Orchestrator"
    direction TB
    turborepo["Turborepo"]:::code
    yarnws["Yarn Workspaces"]:::code
  end

  %% Apps
  subgraph "Apps"
    direction TB
    subgraph "Home App (apps/home)"
      direction TB
      homeConfig["next.config.js, tailwind.config.js, tsconfig.json"]:::code
      homeCode["app/**"]:::code
    end
    subgraph "Blog App (apps/blog)"
      direction TB
      blogConfig["next.config.js, tsconfig.json, tailwind.config.mjs"]:::code
      blogCode["app/**"]:::code
      blogPosts["_posts/**"]:::code
    end
    subgraph "Insights App (apps/insights)"
      direction TB
      insConfig["next.config.js, tsconfig.json, tailwind.config.mjs"]:::code
      insCode["app/**"]:::code
      insUI["components/**"]:::code
      insLib["lib/**"]:::code
    end
    subgraph "CV App (apps/cv)"
      direction TB
      cvConfig["next.config.js, tsconfig.json, tailwind.config.mjs"]:::code
      cvCode["app/**"]:::code
    end
    subgraph "Photos App (apps/photos)"
      direction TB
      photosConfig["next.config.js, tsconfig.json"]:::code
      photosCode["app/**"]:::code
      unsplashLib["lib/unsplash.ts"]:::code
    end
  end

  %% Packages
  subgraph "Packages"
    direction TB
    pkgComponents["packages/components"]:::code
    pkgLibs["packages/libs"]:::code
    pkgInterfaces["packages/interfaces"]:::code
    pkgESLint["packages/eslint-config-custom"]:::code
    pkgPrettier["packages/prettier"]:::code
    pkgTailwind["packages/tailwind-config"]:::code
    pkgTSConfig["packages/tsconfig"]:::code
  end

  %% External Services
  subgraph "External Services"
    direction TB
    cfAPI["Cloudflare API"]:::external
    posthog["PostHog"]:::external
    clickhouse["ClickHouse"]:::external
    wakatime["WakaTime API"]:::external
    unsplash["Unsplash API"]:::external
  end

  %% Deployment & Users
  subgraph "Deployment & CDN"
    direction TB
    cfPages["Cloudflare Pages/CDN"]:::deploy
    browsers["End Users / Browsers"]:::external
  end

  %% Connections
  developer["Developer"]:::external

  developer -->|commits code| husky
  husky -->|runs hooks| ghactions
  ghactions -->|triggers builds/tests| turborepo
  turborepo -->|builds| homeConfig
  turborepo -->|builds| blogConfig
  turborepo -->|builds| insConfig
  turborepo -->|builds| cvConfig
  turborepo -->|builds| photosConfig

  pkgComponents -->|shared UI| homeCode
  pkgComponents -->|shared UI| blogCode
  pkgComponents -->|shared UI| insUI
  pkgComponents -->|shared UI| cvCode
  pkgComponents -->|shared UI| photosCode

  pkgLibs -->|shared logic| blogCode
  pkgLibs -->|shared logic| insLib
  pkgLibs -->|shared logic| photosCode

  pkgInterfaces -->|types| homeCode
  pkgInterfaces -->|types| blogCode
  pkgInterfaces -->|types| insCode
  pkgInterfaces -->|types| cvCode
  pkgInterfaces -->|types| photosCode

  homeCode -->|deploys to| cfPages
  blogCode -->|deploys to| cfPages
  insCode -->|deploys to| cfPages
  cvCode -->|deploys to| cfPages
  photosCode -->|deploys to| cfPages

  cfPages -->|serves static/SSR| browsers

  blogCode -->|fetches MD| blogPosts
  insCode -->|calls| clickhouse
  insCode -->|sends analytics| posthog
  insCode -->|sends metrics| wakatime
  photosCode -->|fetches images| unsplash

  cfAPI -->|deploys| cfPages

  %% Click Events
  click turbojson "https://github.com/duyet/monorepo/blob/master//turbo.json"
  click pkgjson "https://github.com/duyet/monorepo/blob/master//package.json"
  click tsconfig "https://github.com/duyet/monorepo/blob/master//tsconfig.json"
  click prettierignore "https://github.com/duyet/monorepo/blob/master//.prettierignore"
  click commitlint "https://github.com/duyet/monorepo/blob/master//.commitlintrc.js"

  click eslintwf "https://github.com/duyet/monorepo/blob/master//.github/workflows/eslint.yml"
  click testwf "https://github.com/duyet/monorepo/blob/master//.github/workflows/test.yml"
  click oauthwf "https://github.com/duyet/monorepo/blob/master//.github/workflows/claude-oauth.yml"
  click reviewwf "https://github.com/duyet/monorepo/blob/master//.github/workflows/claude-code-review.yml"
  click precommit "https://github.com/duyet/monorepo/tree/master//.husky/pre-commit"
  click commitmsg "https://github.com/duyet/monorepo/tree/master//.husky/commit-msg"

  click turborepo "https://github.com/duyet/monorepo/blob/master//turbo.json"
  click yarnws "https://github.com/duyet/monorepo/blob/master//package.json"

  click homeConfig "https://github.com/duyet/monorepo/blob/master//apps/home/next.config.js"
  click homeConfig "https://github.com/duyet/monorepo/blob/master//apps/home/tailwind.config.js"
  click homeConfig "https://github.com/duyet/monorepo/blob/master//apps/home/tsconfig.json"
  click homeCode "https://github.com/duyet/monorepo/tree/master//apps/home/app"
  
  click blogConfig "https://github.com/duyet/monorepo/blob/master//apps/blog/next.config.js"
  click blogConfig "https://github.com/duyet/monorepo/blob/master//apps/blog/tsconfig.json"
  click blogConfig "https://github.com/duyet/monorepo/blob/master//apps/blog/tailwind.config.mjs"
  click blogCode "https://github.com/duyet/monorepo/tree/master//apps/blog/app"
  click blogPosts "https://github.com/duyet/monorepo/tree/master//apps/blog/_posts"

  click insConfig "https://github.com/duyet/monorepo/blob/master//apps/insights/next.config.js"
  click insConfig "https://github.com/duyet/monorepo/blob/master//apps/insights/tsconfig.json"
  click insConfig "https://github.com/duyet/monorepo/blob/master//apps/insights/tailwind.config.mjs"
  click insCode "https://github.com/duyet/monorepo/tree/master//apps/insights/app"
  click insUI "https://github.com/duyet/monorepo/tree/master//apps/insights/components"
  click insLib "https://github.com/duyet/monorepo/tree/master//apps/insights/lib"

  click cvConfig "https://github.com/duyet/monorepo/blob/master//apps/cv/next.config.js"
  click cvConfig "https://github.com/duyet/monorepo/blob/master//apps/cv/tsconfig.json"
  click cvConfig "https://github.com/duyet/monorepo/blob/master//apps/cv/tailwind.config.mjs"
  click cvCode "https://github.com/duyet/monorepo/tree/master//apps/cv/app"

  click photosConfig "https://github.com/duyet/monorepo/blob/master//apps/photos/next.config.js"
  click photosConfig "https://github.com/duyet/monorepo/blob/master//apps/photos/tsconfig.json"
  click photosCode "https://github.com/duyet/monorepo/tree/master//apps/photos/app"
  click unsplashLib "https://github.com/duyet/monorepo/blob/master//apps/photos/lib/unsplash.ts"

  click pkgComponents "https://github.com/duyet/monorepo/tree/master//packages/components"
  click pkgLibs "https://github.com/duyet/monorepo/tree/master//packages/libs"
  click pkgInterfaces "https://github.com/duyet/monorepo/tree/master//packages/interfaces"
  click pkgESLint "https://github.com/duyet/monorepo/tree/master//packages/eslint-config-custom"
  click pkgPrettier "https://github.com/duyet/monorepo/tree/master//packages/prettier"
  click pkgTailwind "https://github.com/duyet/monorepo/tree/master//packages/tailwind-config"
  click pkgTSConfig "https://github.com/duyet/monorepo/tree/master//packages/tsconfig"

  click cfAPI "https://github.com/duyet/monorepo/blob/master//packages/interfaces/src/cloudflare.ts"
  click cfPages "https://github.com/duyet/monorepo/tree/master//"
  click posthog "https://github.com/duyet/monorepo/blob/master//apps/insights/lib/posthog.ts"
  click clickhouse "https://github.com/duyet/monorepo/blob/master//apps/insights/app/ai/utils/clickhouse-client.ts"
  click wakatime "https://github.com/duyet/monorepo/blob/master//apps/insights/app/wakatime/wakatime-utils.ts"
  click unsplash "https://github.com/duyet/monorepo/blob/master//packages/libs/fetcher.ts"

  %% Styles
  classDef code fill:#D0E8FF,stroke:#0366d6,color:#0366d6
  classDef ci fill:#E6FFFA,stroke:#1F9D55,color:#1F9D55
  classDef deploy fill:#FFF5D0,stroke:#D69E2E,color:#D69E2E
  classDef external fill:#FFE6E6,stroke:#d73a49,color:#d73a49
```
