How mihf05/social-copilot works
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: schema.ts Database · page.tsx Compose · route.ts Accounts API · layout.tsx Dashboard shell
Components 28
Public site
Marketing landing experience and pricing pages
- Landing · Public marketing entrypoint and homepage
app/(landing)/page.tsx - Marketing UI · Hero, features, pricing, testimonials, navbar, footer, platform strip
components/landing
Auth
Sign-in and sign-up flows
- Auth pages · Clerk-powered sign-in and sign-up pages
app/(auth)/sign-in/[[...sign-in]]/page.tsx
Dashboard
Authenticated product areas
- Dashboard shell · Authenticated chrome and shared dashboard layout
app/(dashboard)/layout.tsx - Accounts · Connected social accounts management
app/(dashboard)/accounts/page.tsx - Compose · Draft, preview, schedule, and publish workflow
app/(dashboard)/compose/page.tsx - Calendar · Scheduled posts calendar and post drawers
app/(dashboard)/calendar/page.tsx - Analytics · Performance charts, tables, and plan teaser
components/analytics - Auto-reply · Automation rules UI for engagement responses
app/(dashboard)/auto-reply/page.tsx - Billing · Plan and upgrade flow
app/(dashboard)/billing/page.tsx - Settings · User and product settings
app/(dashboard)/settings/page.tsx
API
Domain route handlers and webhooks
- Accounts API · Persist connected account records
app/api/accounts/route.ts - Posts API · Create and manage post records
app/api/posts/route.ts - Caption API · Generates captions for compose workflow
app/api/ai/caption/route.ts - Upload API · Handles media uploads for composed posts
app/api/media/upload/route.ts - Analytics API · Aggregates overview metrics for dashboard charts
app/api/analytics/overview/route.ts - Auto-reply API · CRUD for automation rules
app/api/auto-reply/route.ts - OAuth API · Platform connect and callback flows
app/api/oauth/[platform]/route.ts - Clerk webhook · Syncs auth lifecycle events into backend state
app/api/webhooks/clerk/route.ts - Inngest API · Receives and dispatches background jobs
app/api/inngest/route.ts
Services
External integrations and shared backend services
- Inngest · Event client, functions, and workers for async processing
lib/inngest/functions.ts - Platform OAuth · Platform-specific OAuth logic
lib/platforms/oauth.ts - Gemini client · Caption generation service client
lib/gemini/client.ts - ImageKit client · External media storage and delivery client
lib/imagekit/client.ts - Plan guard · Subscription-based access control
lib/plan-guard.ts
Data layer
Database schema and migrations
- Database · Primary persistence boundary and ORM setup
lib/db/schema.ts
Shared UI
Reusable layout and design system components
- UI shell · Sidebar, topbar, theme controls, and shared shell UI
components/layout/sidebar.tsx - UI primitives · Reusable base components across the app
components/ui/button.tsx
Connections 27
- 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