# mihf05/social-copilot architecture

> Architecture diagram of the GitHub repository mihf05/social-copilot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mihf05/social-copilot
- Repository: https://github.com/mihf05/social-copilot

## Overview

1. This is a Next.js App Router application organized into three main user-facing areas: a public landing site, an auth flow, and an authenticated dashboard. The route groups under `app/(landing)`, `app/(auth)`, and `app/(dashboard)` show that the UI is segmented by access level and layout, with shared dashboard chrome in `app/(dashboard)/layout.tsx`.

2. The landing experience is marketing-oriented, with dedicated components for hero, features, pricing, testimonials, navbar, footer, and platform strip. That suggests the product is a SaaS app centered on multi-platform social content and publishing, rather than a generic CRUD dashboard.

3. Authentication is handled through route pages for sign-in and sign-up under `app/(auth)/sign-in` and `app/(auth)/sign-up`, and there is also a Clerk webhook endpoint at `app/api/webhooks/clerk/route.ts`. The presence of this webhook indicates the app synchronizes auth/user lifecycle events into its own backend state.

4. The dashboard is split into product modules: accounts, compose, calendar, analytics, auto-reply, billing, and settings. The component structure mirrors that breakdown, with dedicated feature folders such as `components/accounts`, `components/compose`, `components/analytics`, and `components/auto-reply`, so the UI is built as domain-specific panels rather than a single generic admin surface.

5. The core workflow appears to be content creation and scheduling. The compose area includes caption editing, media upload, image editing, platform selection, previewing, and scheduling. The calendar area renders scheduled posts with cards, drawers, and view switching, which implies posts move from draft/composed state into scheduled publication state and are then surfaced in the calendar UI.

6. Backend functionality is exposed through route handlers in `app/api`, grouped by domain: accounts, posts, auto-reply, analytics overview, settings, media upload, AI captioning, OAuth, webhooks, and debug endpoints. This makes the API layer the main boundary between the client-side dashboard and the server-side business logic.

7. Platform connectivity is handled separately from content logic. The `app/api/oauth/[platform]` routes and `lib/platforms/oauth.ts` indicate platform-specific OAuth flows for connecting external social accounts, while `app/api/accounts` manages the persisted account records. This separation is important for diagramming because authorization with a platform is distinct from storing and using the connected account.

8. AI assistance is provided through a Gemini client in `lib/gemini/client.ts` and an API route for caption generation. That means caption creation is an externalized service dependency, likely feeding the compose workflow rather than replacing it; it sits on the server side and is invoked by the UI via the API.

9. Media handling is also delegated to an external service via `lib/imagekit/client.ts` and `app/api/media/upload/route.ts`. In architecture terms, uploads flow from the compose UI to the upload API, then out to ImageKit, with the resulting asset URLs feeding back into post composition and preview.

10. Persistent application data is managed through Drizzle ORM in `lib/db`, with schema definitions in `lib/db/schema.ts` and migration artifacts under `drizzle/`. This is the main persistence boundary for accounts, posts, auto-reply rules, settings, and related product state.

11. Background and event-driven processing is powered by Inngest. The repo includes an Inngest client, function registrations, an API endpoint at `app/api/inngest/route.ts`, and a worker specifically for comment monitoring in `lib/inngest/workers/comment-monitor.ts`. That indicates some tasks run asynchronously outside the request/response path, likely for monitoring engagement or triggering automated replies.

12. The auto-reply feature is a distinct subsystem with both UI and API support. The rule form and rules list on the front end, plus `app/api/auto-reply`, suggest users define automation rules that are stored in the database and then applied by backend workers or scheduled processes.

13. Analytics is presented as a read-only dashboard layer with charts, tables, date-range controls, and a premium teaser. The route `app/api/analytics/overview` likely aggregates data from persisted posts/accounts and external platform metrics, which the analytics components then visualize.

14. Billing and plan enforcement are present as a separate concern, not just a UI page. The `components/billing/upgrade-modal.tsx` and `lib/plan-guard.ts` indicate feature gating tied to subscription tier, so premium capabilities such as analytics depth or automation likely depend on plan state.

15. Shared infrastructure is concentrated under `lib` and reusable UI primitives under `components/ui`. The former contains integrations and cross-cutting utilities, while the latter is a design-system layer used by all feature modules; this keeps the architecture split between product logic and presentation primitives.

16. Overall, the system is a multi-tenant social content management SaaS: authenticated users connect external platforms, create and schedule posts with AI/media assistance, review performance analytics, and configure automation. The key diagram boundaries should be public marketing, auth, dashboard UI, API/domain services, third-party integrations, and background workers.

Main entry points: [`lib/db/schema.ts`](https://github.com/mihf05/social-copilot/blob/main/lib/db/schema.ts) (Database), [`app/(dashboard)/compose/page.tsx`](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/compose/page.tsx) (Compose), [`app/api/accounts/route.ts`](https://github.com/mihf05/social-copilot/blob/main/app/api/accounts/route.ts) (Accounts API), [`app/(dashboard)/layout.tsx`](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/layout.tsx) (Dashboard shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public site"]
  node_app_landing["Landing<br/>Next.js route group<br/>[page.tsx]"]
  node_landing_components["Marketing UI<br/>landing components"]
end

subgraph group_auth["Auth"]
  node_app_auth["Auth pages<br/>Next.js route group<br/>[page.tsx]"]
end

subgraph group_dashboard["Dashboard"]
  node_app_dashboard_layout["Dashboard shell<br/>app layout<br/>[layout.tsx]"]
  node_dash_accounts["Accounts<br/>dashboard module<br/>[page.tsx]"]
  node_dash_compose["Compose<br/>dashboard module<br/>[page.tsx]"]
  node_dash_calendar["Calendar<br/>dashboard module<br/>[page.tsx]"]
  node_dash_analytics["Analytics<br/>dashboard module"]
  node_dash_autoreply["Auto-reply<br/>dashboard module<br/>[page.tsx]"]
  node_dash_billing["Billing<br/>dashboard module<br/>[page.tsx]"]
  node_dash_settings["Settings<br/>dashboard module<br/>[page.tsx]"]
end

subgraph group_api["API"]
  node_api_accounts["Accounts API<br/>REST routes<br/>[route.ts]"]
  node_api_posts["Posts API<br/>REST routes<br/>[route.ts]"]
  node_api_compose_ai["Caption API<br/>AI route<br/>[route.ts]"]
  node_api_media["Upload API<br/>media route<br/>[route.ts]"]
  node_api_analytics["Analytics API<br/>analytics route<br/>[route.ts]"]
  node_api_autoreply["Auto-reply API<br/>automation routes<br/>[route.ts]"]
  node_api_oauth["OAuth API<br/>platform auth routes<br/>[route.ts]"]
  node_api_webhooks["Clerk webhook<br/>webhook route<br/>[route.ts]"]
  node_api_inngest["Inngest API<br/>event endpoint<br/>[route.ts]"]
end

subgraph group_services["Services"]
  node_lib_inngest["Inngest<br/>background jobs<br/>[functions.ts]"]
  node_lib_platforms["Platform OAuth<br/>integration helper<br/>[oauth.ts]"]
  node_lib_gemini["Gemini client<br/>AI integration<br/>[client.ts]"]
  node_lib_imagekit["ImageKit client<br/>media integration<br/>[client.ts]"]
  node_lib_plan_guard["Plan guard<br/>feature gating<br/>[plan-guard.ts]"]
end

subgraph group_data["Data layer"]
  node_lib_db[("Database<br/>Drizzle schema<br/>[schema.ts]")]
end

subgraph group_shared["Shared UI"]
  node_ui_shell["UI shell<br/>layout components<br/>[sidebar.tsx]"]
  node_ui_primitives["UI primitives<br/>design system<br/>[button.tsx]"]
end

node_app_landing -->|"renders"| node_landing_components
node_app_auth -.->|"syncs via"| node_api_webhooks
node_app_dashboard_layout -->|"uses"| node_ui_shell
node_app_dashboard_layout -.->|"guards"| node_lib_plan_guard
node_dash_accounts -->|"reads/writes"| node_api_accounts
node_dash_compose -->|"creates"| node_api_posts
node_dash_compose -->|"requests"| node_api_compose_ai
node_dash_compose -->|"uploads"| node_api_media
node_dash_compose -.->|"uses"| node_api_accounts
node_dash_calendar -->|"lists"| node_api_posts
node_dash_analytics -->|"loads"| node_api_analytics
node_dash_autoreply -->|"manages"| node_api_autoreply
node_dash_billing -.->|"enforces"| node_lib_plan_guard
node_api_accounts -->|"persists"| node_lib_db
node_api_posts -->|"persists"| node_lib_db
node_api_compose_ai -->|"calls"| node_lib_gemini
node_api_media -->|"stores"| node_lib_imagekit
node_api_analytics -->|"aggregates"| node_lib_db
node_api_autoreply -->|"persists"| node_lib_db
node_api_oauth -->|"connects"| node_lib_platforms
node_api_oauth -.->|"completes setup"| node_api_accounts
node_api_webhooks -->|"updates"| node_lib_db
node_api_inngest -->|"dispatches"| node_lib_inngest
node_lib_inngest -->|"reads/writes"| node_lib_db
node_lib_inngest -.->|"supports"| node_api_autoreply
node_dash_analytics -.->|"tiers"| node_lib_plan_guard
node_app_dashboard_layout -->|"built on"| node_ui_primitives

click node_app_landing "https://github.com/mihf05/social-copilot/blob/main/app/(landing)/page.tsx"
click node_landing_components "https://github.com/mihf05/social-copilot/tree/main/components/landing"
click node_app_auth "https://github.com/mihf05/social-copilot/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.tsx"
click node_app_dashboard_layout "https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/layout.tsx"
click node_dash_accounts "https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/accounts/page.tsx"
click node_dash_compose "https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/compose/page.tsx"
click node_dash_calendar "https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/calendar/page.tsx"
click node_dash_analytics "https://github.com/mihf05/social-copilot/tree/main/components/analytics"
click node_dash_autoreply "https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/auto-reply/page.tsx"
click node_dash_billing "https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/billing/page.tsx"
click node_dash_settings "https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/settings/page.tsx"
click node_api_accounts "https://github.com/mihf05/social-copilot/blob/main/app/api/accounts/route.ts"
click node_api_posts "https://github.com/mihf05/social-copilot/blob/main/app/api/posts/route.ts"
click node_api_compose_ai "https://github.com/mihf05/social-copilot/blob/main/app/api/ai/caption/route.ts"
click node_api_media "https://github.com/mihf05/social-copilot/blob/main/app/api/media/upload/route.ts"
click node_api_analytics "https://github.com/mihf05/social-copilot/blob/main/app/api/analytics/overview/route.ts"
click node_api_autoreply "https://github.com/mihf05/social-copilot/blob/main/app/api/auto-reply/route.ts"
click node_api_oauth "https://github.com/mihf05/social-copilot/blob/main/app/api/oauth/[platform]/route.ts"
click node_api_webhooks "https://github.com/mihf05/social-copilot/blob/main/app/api/webhooks/clerk/route.ts"
click node_api_inngest "https://github.com/mihf05/social-copilot/blob/main/app/api/inngest/route.ts"
click node_lib_db "https://github.com/mihf05/social-copilot/blob/main/lib/db/schema.ts"
click node_lib_inngest "https://github.com/mihf05/social-copilot/blob/main/lib/inngest/functions.ts"
click node_lib_platforms "https://github.com/mihf05/social-copilot/blob/main/lib/platforms/oauth.ts"
click node_lib_gemini "https://github.com/mihf05/social-copilot/blob/main/lib/gemini/client.ts"
click node_lib_imagekit "https://github.com/mihf05/social-copilot/blob/main/lib/imagekit/client.ts"
click node_lib_plan_guard "https://github.com/mihf05/social-copilot/blob/main/lib/plan-guard.ts"
click node_ui_shell "https://github.com/mihf05/social-copilot/blob/main/components/layout/sidebar.tsx"
click node_ui_primitives "https://github.com/mihf05/social-copilot/blob/main/components/ui/button.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_landing,node_landing_components,node_ui_shell,node_ui_primitives toneBlue
class node_app_auth toneAmber
class node_app_dashboard_layout,node_dash_accounts,node_dash_compose,node_dash_calendar,node_dash_analytics,node_dash_autoreply,node_dash_billing,node_dash_settings toneMint
class node_api_accounts,node_api_posts,node_api_compose_ai,node_api_media,node_api_analytics,node_api_autoreply,node_api_oauth,node_api_webhooks,node_api_inngest toneRose
class node_lib_inngest,node_lib_platforms,node_lib_gemini,node_lib_imagekit,node_lib_plan_guard toneIndigo
class node_lib_db toneTeal
```

## Components

### Public site

Marketing landing experience and pricing pages

- [Landing](https://github.com/mihf05/social-copilot/blob/main/app/(landing)/page.tsx): Next.js route group · Public marketing entrypoint and homepage · `app/(landing)/page.tsx`
- [Marketing UI](https://github.com/mihf05/social-copilot/tree/main/components/landing): landing components · Hero, features, pricing, testimonials, navbar, footer, platform strip · `components/landing`

### Auth

Sign-in and sign-up flows

- [Auth pages](https://github.com/mihf05/social-copilot/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.tsx): Next.js route group · Clerk-powered sign-in and sign-up pages · `app/(auth)/sign-in/[[...sign-in]]/page.tsx`

### Dashboard

Authenticated product areas

- [Dashboard shell](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/layout.tsx): app layout · Authenticated chrome and shared dashboard layout · `app/(dashboard)/layout.tsx`
- [Accounts](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/accounts/page.tsx): dashboard module · Connected social accounts management · `app/(dashboard)/accounts/page.tsx`
- [Compose](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/compose/page.tsx): dashboard module · Draft, preview, schedule, and publish workflow · `app/(dashboard)/compose/page.tsx`
- [Calendar](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/calendar/page.tsx): dashboard module · Scheduled posts calendar and post drawers · `app/(dashboard)/calendar/page.tsx`
- [Analytics](https://github.com/mihf05/social-copilot/tree/main/components/analytics): dashboard module · Performance charts, tables, and plan teaser · `components/analytics`
- [Auto-reply](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/auto-reply/page.tsx): dashboard module · Automation rules UI for engagement responses · `app/(dashboard)/auto-reply/page.tsx`
- [Billing](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/billing/page.tsx): dashboard module · Plan and upgrade flow · `app/(dashboard)/billing/page.tsx`
- [Settings](https://github.com/mihf05/social-copilot/blob/main/app/(dashboard)/settings/page.tsx): dashboard module · User and product settings · `app/(dashboard)/settings/page.tsx`

### API

Domain route handlers and webhooks

- [Accounts API](https://github.com/mihf05/social-copilot/blob/main/app/api/accounts/route.ts): REST routes · Persist connected account records · `app/api/accounts/route.ts`
- [Posts API](https://github.com/mihf05/social-copilot/blob/main/app/api/posts/route.ts): REST routes · Create and manage post records · `app/api/posts/route.ts`
- [Caption API](https://github.com/mihf05/social-copilot/blob/main/app/api/ai/caption/route.ts): AI route · Generates captions for compose workflow · `app/api/ai/caption/route.ts`
- [Upload API](https://github.com/mihf05/social-copilot/blob/main/app/api/media/upload/route.ts): media route · Handles media uploads for composed posts · `app/api/media/upload/route.ts`
- [Analytics API](https://github.com/mihf05/social-copilot/blob/main/app/api/analytics/overview/route.ts): analytics route · Aggregates overview metrics for dashboard charts · `app/api/analytics/overview/route.ts`
- [Auto-reply API](https://github.com/mihf05/social-copilot/blob/main/app/api/auto-reply/route.ts): automation routes · CRUD for automation rules · `app/api/auto-reply/route.ts`
- [OAuth API](https://github.com/mihf05/social-copilot/blob/main/app/api/oauth/[platform]/route.ts): platform auth routes · Platform connect and callback flows · `app/api/oauth/[platform]/route.ts`
- [Clerk webhook](https://github.com/mihf05/social-copilot/blob/main/app/api/webhooks/clerk/route.ts): webhook route · Syncs auth lifecycle events into backend state · `app/api/webhooks/clerk/route.ts`
- [Inngest API](https://github.com/mihf05/social-copilot/blob/main/app/api/inngest/route.ts): event endpoint · Receives and dispatches background jobs · `app/api/inngest/route.ts`

### Services

External integrations and shared backend services

- [Inngest](https://github.com/mihf05/social-copilot/blob/main/lib/inngest/functions.ts): background jobs · Event client, functions, and workers for async processing · `lib/inngest/functions.ts`
- [Platform OAuth](https://github.com/mihf05/social-copilot/blob/main/lib/platforms/oauth.ts): integration helper · Platform-specific OAuth logic · `lib/platforms/oauth.ts`
- [Gemini client](https://github.com/mihf05/social-copilot/blob/main/lib/gemini/client.ts): AI integration · Caption generation service client · `lib/gemini/client.ts`
- [ImageKit client](https://github.com/mihf05/social-copilot/blob/main/lib/imagekit/client.ts): media integration · External media storage and delivery client · `lib/imagekit/client.ts`
- [Plan guard](https://github.com/mihf05/social-copilot/blob/main/lib/plan-guard.ts): feature gating · Subscription-based access control · `lib/plan-guard.ts`

### Data layer

Database schema and migrations

- [Database](https://github.com/mihf05/social-copilot/blob/main/lib/db/schema.ts): Drizzle schema · Primary persistence boundary and ORM setup · `lib/db/schema.ts`

### Shared UI

Reusable layout and design system components

- [UI shell](https://github.com/mihf05/social-copilot/blob/main/components/layout/sidebar.tsx): layout components · Sidebar, topbar, theme controls, and shared shell UI · `components/layout/sidebar.tsx`
- [UI primitives](https://github.com/mihf05/social-copilot/blob/main/components/ui/button.tsx): design system · Reusable base components across the app · `components/ui/button.tsx`

## Connections

- Landing → Marketing UI: renders · Homepage composes marketing sections from landing components
- Auth pages → Clerk webhook: syncs via · Auth lifecycle events are reflected into backend state
- Dashboard shell → UI shell: uses · Dashboard chrome is built from shared shell components
- Dashboard shell → Plan guard: guards · Feature access is constrained by plan state
- Accounts → Accounts API: reads/writes · Connected accounts are managed through the accounts API
- Compose → Posts API: creates · Composed drafts are persisted as posts
- Compose → Caption API: requests · Caption generation is invoked during composition
- Compose → Upload API: uploads · Media assets flow through the upload API
- Compose → Accounts API: uses · Compose needs connected accounts and platform context
- Calendar → Posts API: lists · Calendar view renders scheduled posts from persistence
- Analytics → Analytics API: loads · Charts and tables consume aggregated analytics data
- Auto-reply → Auto-reply API: manages · Automation rules are edited and stored through API routes
- Billing → Plan guard: enforces · Upgrade and entitlement behavior is plan-driven
- Accounts API → Database: persists · Account records are stored in the database
- Posts API → Database: persists · Posts and scheduling state are stored in the database
- Caption API → Gemini client: calls · Caption generation delegates to Gemini
- Upload API → ImageKit client: stores · Uploads are sent to ImageKit
- Analytics API → Database: aggregates · Overview metrics are derived from persisted product data
- Auto-reply API → Database: persists · Automation rules are stored in the database
- OAuth API → Platform OAuth: connects · Platform-specific OAuth flows are handled separately from account storage
- OAuth API → Accounts API: completes setup · OAuth results feed into connected account records
- Clerk webhook → Database: updates · Webhook events reconcile user and account state
- Inngest API → Inngest: dispatches · Inngest endpoint triggers background functions
- Inngest → Database: reads/writes · Workers operate on persisted posts, rules, and engagement state
- Inngest → Auto-reply API: supports · Async workers power automation and monitoring flows
- Analytics → Plan guard: tiers · Premium analytics are gated by subscription tier
- Dashboard shell → UI primitives: built on · Feature modules share the base design system
