# firaghost/mirach-social architecture

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

- Interactive diagram: https://gitdiagram.com/firaghost/mirach-social
- Repository: https://github.com/firaghost/mirach-social

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ========== Actors / Trust Boundaries ==========
  subgraph "Untrusted Client"
    USER["Content_Manager_User"]:::actor
    BROWSER["Web_Browser"]:::client
    USER -->|"uses"| BROWSER
  end

  subgraph "Trusted Compute (Vercel)"
    subgraph "Next.js_App_(App_Router)"
      APP_SHELL["App_Shell_(Layout_+_Globals)"]:::shell

      subgraph "UI_Routes_(Pages)"
        UI_HOME["/ (Dashboard/Home)"]:::ui
        UI_CAL["/calendar (Content_Calendar)"]:::ui
        UI_COMP["/composer (Post_Composer)"]:::ui
        UI_ANALYTICS["/analytics (Analytics_View)"]:::ui
        UI_SETTINGS["/settings (LinkedIn_Connect_+_Settings)"]:::ui
      end

      subgraph "Reusable_UI_Components"
        C_SIDEBAR["Sidebar (Navigation)"]:::component
        C_COMPOSER["Composer (Compose/Edit)"]:::component
        C_POSTSLIST["PostsList (Draft/Approved/Posted)"]:::component
        C_QUEUE["QueueManager (Approve_+_Schedule)"]:::component
      end

      subgraph "Serverless_API_Routes"
        API_OAUTH_START["/api/auth/linkedin (OAuth_Start)"]:::api
        API_OAUTH_CB["/api/auth/linkedin/callback (OAuth_Callback)"]:::api
        API_UPLOAD["/api/upload (Media_Upload)"]:::api
        API_POST["/api/post-linkedin (Publish_To_LinkedIn)"]:::api
      end

      subgraph "Shared_Library"
        LIB_SUPABASE["Supabase_Client_Wrapper"]:::lib
      end
    end
  end

  subgraph "Data Layer (Supabase)"
    SB_DB[("Postgres_DB")]:::db
    SB_STORAGE[("Storage_Bucket")]:::storage
  end

  subgraph "External Services (LinkedIn_Platform)"
    LI_OAUTH["OAuth_Authorize_Endpoint"]:::external
    LI_TOKEN["OAuth_Token_Endpoint"]:::external
    LI_POSTING["Posting_API (UGC/Assets)"]:::external
  end

  %% ========== Primary navigation ==========
  BROWSER -->|"loads_UI"| UI_HOME
  BROWSER -->|"loads_UI"| UI_CAL
  BROWSER -->|"loads_UI"| UI_COMP
  BROWSER -->|"loads_UI"| UI_ANALYTICS
  BROWSER -->|"loads_UI"| UI_SETTINGS

  %% ========== App shell / composition ==========
  APP_SHELL -->|"wraps"| UI_HOME
  APP_SHELL -->|"wraps"| UI_CAL
  APP_SHELL -->|"wraps"| UI_COMP
  APP_SHELL -->|"wraps"| UI_ANALYTICS
  APP_SHELL -->|"wraps"| UI_SETTINGS

  UI_HOME -->|"renders"| C_SIDEBAR
  UI_CAL -->|"renders"| C_SIDEBAR
  UI_COMP -->|"renders"| C_SIDEBAR
  UI_ANALYTICS -->|"renders"| C_SIDEBAR
  UI_SETTINGS -->|"renders"| C_SIDEBAR

  UI_COMP -->|"uses"| C_COMPOSER
  UI_HOME -->|"uses"| C_POSTSLIST
  UI_CAL -->|"uses"| C_POSTSLIST
  UI_HOME -->|"uses"| C_QUEUE
  UI_CAL -->|"uses"| C_QUEUE

  %% ========== Supabase integration ==========
  LIB_SUPABASE -->|"connects_to"| SB_DB
  LIB_SUPABASE -->|"connects_to"| SB_STORAGE

  %% UI direct reads/writes (RLS enforced)
  UI_HOME -->|"reads/writes_posts (RLS)"| LIB_SUPABASE
  UI_CAL -->|"reads_schedule (RLS)"| LIB_SUPABASE
  UI_COMP -->|"saves_drafts (RLS)"| LIB_SUPABASE
  UI_ANALYTICS -->|"reads_internal_analytics (RLS)"| LIB_SUPABASE
  UI_SETTINGS -->|"reads_settings (RLS)"| LIB_SUPABASE

  %% ========== API routes use shared supabase client ==========
  API_OAUTH_START -->|"uses"| LIB_SUPABASE
  API_OAUTH_CB -->|"uses"| LIB_SUPABASE
  API_UPLOAD -->|"uses"| LIB_SUPABASE
  API_POST -->|"uses"| LIB_SUPABASE

  %% ========== Flow 2: LinkedIn OAuth connect (redirects) ==========
  UI_SETTINGS -->|"1_start_OAuth"| API_OAUTH_START
  API_OAUTH_START -.->|"2_redirect_to_authorize"| LI_OAUTH
  LI_OAUTH -.->|"3_redirect_back_with_code"| API_OAUTH_CB
  API_OAUTH_CB -->|"4_exchange_code_for_token"| LI_TOKEN
  API_OAUTH_CB -->|"5_store_tokens/account_link"| SB_DB

  %% ========== Flow 3: Upload media ==========
  C_COMPOSER -->|"upload_media"| API_UPLOAD
  API_UPLOAD -->|"store_asset"| SB_STORAGE
  API_UPLOAD -->|"persist_asset_ref"| SB_DB
  API_UPLOAD -->|"return_asset_url/id"| C_COMPOSER

  %% ========== Flow 4: Approve -> Post to LinkedIn ==========
  C_QUEUE -->|"update_status_draft->approved"| SB_DB
  C_QUEUE -->|"trigger_publish (manual_or_scheduled)"| API_POST
  API_POST -->|"fetch_post+token"| SB_DB
  API_POST -->|"create_post"| LI_POSTING
  API_POST -->|"write_back_posted_status+linkedin_id"| SB_DB

  %% ========== Workflow annotation ==========
  subgraph "Workflow_State_Machine (Post_Status)"
    W1["draft"]:::state
    W2["approved"]:::state
    W3["posted"]:::state
    W1 -->|"approve"| W2
    W2 -->|"publish"| W3
  end
  C_QUEUE ---|"manages"| W1
  C_QUEUE ---|"manages"| W2
  C_QUEUE ---|"manages"| W3

  %% ========== Click Events (component mapping) ==========
  click APP_SHELL "https://github.com/firaghost/mirach-social/blob/main/src/app/layout.tsx"
  click UI_HOME "https://github.com/firaghost/mirach-social/blob/main/src/app/page.tsx"
  click UI_CAL "https://github.com/firaghost/mirach-social/blob/main/src/app/calendar/page.tsx"
  click UI_COMP "https://github.com/firaghost/mirach-social/blob/main/src/app/composer/page.tsx"
  click UI_ANALYTICS "https://github.com/firaghost/mirach-social/blob/main/src/app/analytics/page.tsx"
  click UI_SETTINGS "https://github.com/firaghost/mirach-social/blob/main/src/app/settings/page.tsx"

  click C_SIDEBAR "https://github.com/firaghost/mirach-social/blob/main/src/components/Sidebar.tsx"
  click C_COMPOSER "https://github.com/firaghost/mirach-social/blob/main/src/components/Composer.tsx"
  click C_POSTSLIST "https://github.com/firaghost/mirach-social/blob/main/src/components/PostsList.tsx"
  click C_QUEUE "https://github.com/firaghost/mirach-social/blob/main/src/components/QueueManager.tsx"

  click API_OAUTH_START "https://github.com/firaghost/mirach-social/blob/main/src/app/api/auth/linkedin/route.ts"
  click API_OAUTH_CB "https://github.com/firaghost/mirach-social/blob/main/src/app/api/auth/linkedin/callback/route.ts"
  click API_POST "https://github.com/firaghost/mirach-social/blob/main/src/app/api/post-linkedin/route.ts"
  click API_UPLOAD "https://github.com/firaghost/mirach-social/blob/main/src/app/api/upload/route.ts"

  click LIB_SUPABASE "https://github.com/firaghost/mirach-social/blob/main/src/lib/supabase.ts"
  click SB_DB "https://github.com/firaghost/mirach-social/blob/main/supabase/schema.sql"
  click LI_OAUTH "https://github.com/firaghost/mirach-social/blob/main/LINKEDIN_SETUP.md"
  click LI_TOKEN "https://github.com/firaghost/mirach-social/blob/main/LINKEDIN_SETUP.md"
  click LI_POSTING "https://github.com/firaghost/mirach-social/blob/main/LINKEDIN_SETUP.md"

  %% ========== Styles ==========
  classDef actor fill:#111827,stroke:#0f172a,color:#ffffff,stroke-width:1px
  classDef client fill:#1f2937,stroke:#111827,color:#ffffff,stroke-width:1px
  classDef shell fill:#0b3a6e,stroke:#0a2a4f,color:#ffffff,stroke-width:1px
  classDef ui fill:#2563eb,stroke:#1e40af,color:#ffffff,stroke-width:1px
  classDef component fill:#1d4ed8,stroke:#1e3a8a,color:#ffffff,stroke-width:1px
  classDef api fill:#f97316,stroke:#c2410c,color:#111827,stroke-width:1px
  classDef lib fill:#60a5fa,stroke:#1d4ed8,color:#0b1220,stroke-width:1px
  classDef db fill:#16a34a,stroke:#166534,color:#ffffff,stroke-width:1px
  classDef storage fill:#22c55e,stroke:#15803d,color:#0b1220,stroke-width:1px
  classDef external fill:#9ca3af,stroke:#4b5563,color:#111827,stroke-width:1px
  classDef state fill:#a78bfa,stroke:#6d28d9,color:#0b1220,stroke-width:1px
```
