How firaghost/mirach-social works
Project type & purpose (what you’re diagramming)
This is a full-stack Next.js (App Router) application deployed on Vercel, using Supabase (Postgres + likely Auth/Storage) as its backend data layer, and integrating with LinkedIn OAuth + posting APIs. It implements a social media management workflow for MIRACH POS:
• Content calendar + queue
• Approval workflow (draft → approve → post)
• LinkedIn integration
• Basic analytics view
Frontend (Next.js pages / UI routes)
Located under src/app/*:
• src/app/page.tsx (likely dashboard/home)
• src/app/calendar/page.tsx (content calendar)
• src/app/composer/page.tsx (post composer)
• src/app/analytics/page.tsx (analytics)
• src/app/settings/page.tsx (settings)
• src/app/layout.tsx, src/app/globals.css (app shell styling)
UI components (reusable building blocks)
src/components/*:
• Composer.tsx (compose/edit posts)
• PostsList.tsx (list drafts/approved/posts)
• QueueManager.tsx (approval workflow + scheduling queue)
• Sidebar.tsx (navigation)
Backend (Next.js API routes = serverless functions on Vercel)
src/app/api/*:
• api/auth/linkedin/route.ts + api/auth/linkedin/callback/route.ts
→ LinkedIn OAuth initiation + callback exchange (code → token), possibly saving tokens in Supabase.
• api/post-linkedin/route.ts
→ “publish” endpoint that calls LinkedIn posting APIs.
• api/upload/route.ts
→ upload media endpoint (often to Supabase Storage or another store).
Data layer / integrations
• src/lib/supabase.ts → central Supabase client creation/usage (DB + auth + storage)
• supabase/schema.sql → defines tables for posts, approvals/status, schedule times, analytics events, maybe user/workspace settings and OAuth tokens.
Config / deployment
• next.config.js, package.json, tailwind.config.js, postcss.config.js, .env.local.example
• README explicitly says deploy to Vercel.
What
For this project, “best and most accurate” usually means drawing three layers and then drilling into subcomponents:
Client / UI layer
• Web Browser
• Next.js React UI (App Router pages)
• Calendar
• Composer
• Analytics
• Settings
• Shared components (Sidebar, QueueManager, PostsList)
Application / API layer (server-side)
• Vercel-hosted Next.js App
• Serverless API Routes
• /api/auth/linkedin (OAuth start)
• /api/auth/linkedin/callback (OAuth callback)
• /api/post-linkedin (publishing)
• /api/upload (media upload)
Data + external services
• Supabase
• Postgres DB (tables defined in schema.sql)
• (Likely) Storage bucket for uploads (because api/upload exists)
• (Potentially) Supabase Auth (not explicitly in tree, but common)
• LinkedIn Platform
• OAuth Authorization endpoint
• Token endpoint (access token retrieval/refresh)
• LinkedIn Posting API (UGC posts, assets)
• Possibly Analytics endpoints (or you track analytics internally in DB)
Pages/Components → Supabase (read/write posts, status, schedule)
• This may be direct from client (Supabase JS client) or via API routes; the repo suggests src/lib/supabase.ts could be used in either environment. Represent both possibilities:
When posting is triggered (manual “Post now” or scheduled)
• Browser or scheduled job → /api/post-linkedin
• /api/post-linkedin → Supabase (fetch post content + linked account token)
• /api/post-linkedin → LinkedIn Posting API
• /api/post-linkedin → Supabase (write back result: posted status, LinkedIn post ID, timestamps)
Flow 5: Analytics
• Internal analytics: UI events / post performance stored in Supabase and rendered in /analytics
• LinkedIn analytics pull: /analytics page triggers API route (not present yet) to pull metrics from LinkedIn. Since there’s no api/analytics route in tree, assume internal tracking for now.
Architectural patterns/principles to highlight
• Monorepo single deployable: Next.js frontend + backend routes in one project.
• Serverless backend: API routes are stateless functions (good to note for token storage and scheduling).
• Integration boundary: LinkedIn is an external trust boundary; tokens/secrets never live in the browser. Show token exchange happening only in API routes.
Diagramming conventions to apply (clear + detailed)
Explicitly:
• Labels: use the exact route paths and file hints, e.g.
“/api/post-linkedin (src/app/api/post-linkedin/route.ts)”
• “reads/writes posts”
• “stores OAuth tokens”
• “uploads media asset”
• “creates LinkedIn post”
• Blue rectangles: UI/pages
• Orange rectangles: API routes (serverless)
• Green bucket: Storage (Supabase Storage)
• Gray cloud: LinkedIn external services
trust boundaries:
• “Browser (untrusted)” vs “Serverless (trusted)” vs “External (LinkedIn)” vs “Data (Supabase)”.
Extra detail to add because the repo is small (don’t overthink; split into components)
• Each App page route
• Each API route
• Supabase into DB vs Storage
• LinkedIn into OAuth vs Posting endpoints
• Workflow statuses as a mini state machine annotation