# mohamed-mudawi/blip architecture

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

- Interactive diagram: https://gitdiagram.com/mohamed-mudawi/blip
- Repository: https://github.com/mohamed-mudawi/blip

## Overview

1. **Core shape of the repo**
   - This is a **Next.js App Router** application. The architecture is a single deployable web app that combines:
     - server-rendered/pages UI,
     - API route handlers,
     - OAuth integrations for **Instagram** and **Twitter/X**,
     - local file upload handling,
     - and backend services via **Supabase** and **Prisma**.

2. **User-facing application layer**
   - The main UI lives under `app/`:
     - `app/page.tsx` is the root entry.
     - `app/home/page.tsx`, `app/login/page.tsx`, `app/signup/page.tsx`, and `app/settings/page.tsx` define the main screens.
     - `app/layout.tsx` and `app/globals.css` provide shared layout and styling.
   - Shared UI components are in `app/components/`, including:
     - `SocialMediaPoster.tsx` / `SocialMediaPoster-updated.tsx` for the posting experience,
     - `TopBar.tsx`,
     - `UserMenu.tsx`.
   - For a diagram, this is the browser-facing presentation layer.

3. **Primary product capability: social posting**
   - The app is built around a “social media poster” workflow.
   - The UI likely collects content/media and sends it to backend routes that post to one or both platforms.
   - The two platform-specific integrations are separate subsystems, not a single generic social API:
     - `app/api/auth/instagram/*`
     - `app/api/auth/twitter/*`

4. **Instagram integration subsystem**
   - Instagram-specific backend logic is split into route handlers:
     - `route.ts` for starting auth or handling the main integration endpoint,
     - `callback/route.ts` for OAuth return handling,
     - `status/route.ts` for checking connection state,
     - `post/route.ts` for publishing content,
     - `logout/route.ts` for disconnecting.
   - This indicates a full lifecycle: connect → verify status → post → disconnect.
   - In an architecture diagram, Instagram should be shown as an external OAuth/API dependency connected through these route handlers.

5. **Twitter/X integration subsystem**
   - Twitter follows the same pattern as Instagram:
     - `route.ts`,
     - `callback/route.ts`,
     - `status/route.ts`,
     - `post/route.ts`,
     - `logout/route.ts`.
   - The mirrored structure suggests the app abstracts “platform integration” at the UI level but keeps platform-specific server logic isolated.
   - Twitter/X is also an external dependency reached only through backend routes, not directly from the client.

6. **Auth and callback boundaries**
   - There are two distinct callback areas:
     - platform callbacks under `app/api/auth/*/callback`,
     - and a generic `app/auth/callback/route.ts`.
   - This suggests the app has at least one broader auth redirect/callback path in addition to the social-provider flows.
   - For an architecture diagram, treat callback handling as a key boundary where the app receives redirects from external identity/providers and exchanges them for internal session/state.

7. **Upload and media handling**
   - `app/api/uploads/route.ts` and `public/uploads/` indicate the app supports file upload workflows.
   - The upload endpoint is likely the bridge between browser-selected media and the posting pipeline.
   - `public/uploads/` implies uploaded assets are stored in the app’s public file area, so media becomes retrievable by URL for later use in posting flows.

8. **Backend/data layer**
   - `lib/supabase.ts` shows the app integrates with **Supabase** as a backend service.
   - `prisma/schema.prisma` and `prisma.config.ts` show **Prisma** is used for database schema and access patterns.
   - This means persistence is not just local state; there is a structured data layer for users, connections, tokens, post metadata, or related records.
   - In a diagram, place Supabase/DB beneath the app as the persistence/auth-support tier.

9. **Operational endpoints**
   - `app/api/health/route.ts` provides a health check endpoint, which is useful for deployment monitoring and uptime checks.
   - This is a small but important operational boundary separate from product flows.
   - It indicates the app is intended to be deployed as a hosted service rather than just run locally.

10. **Tooling and runtime**
   - The project is TypeScript-based (`tsconfig.json`) with Next.js config and standard frontend tooling:
     - `eslint.config.mjs`,
     - `postcss.config.mjs`,
     - `next.config.ts`,
     - `package.json` / lockfile.
   - The repo follows the App Router convention, so both UI and API live in the same codebase and runtime.
   - Deployment is likely serverless-friendly, with route handlers serving as the backend surface.

11. **Important architecture boundaries to draw**
   - **Browser/UI boundary:** pages and components in `app/`.
   - **App backend boundary:** route handlers in `app/api/` and `app/auth/`.
   - **External provider boundary:** Instagram, Twitter/X, and Supabase.
   - **Storage boundary:** `public/uploads/` for uploaded media.
   - **Data boundary:** Prisma-managed database models and Supabase integration.

12. **Overall flow**
   - A user opens the Next.js UI, authenticates or connects a social account, optionally uploads media, and triggers a post action.
   - The client talks to internal route handlers, which then:
     - manage OAuth callbacks,
     - persist or read state via the backend/data layer,
     - and call Instagram/Twitter APIs to complete posting.
   - The app therefore behaves as a compact orchestration layer between the user, local media storage, and multiple external services.

Main entry points: [`app/components/SocialMediaPoster.tsx`](https://github.com/mohamed-mudawi/blip/blob/main/app/components/SocialMediaPoster.tsx) (Poster), [`app/page.tsx`](https://github.com/mohamed-mudawi/blip/blob/main/app/page.tsx) (App shell), [`app/home/page.tsx`](https://github.com/mohamed-mudawi/blip/blob/main/app/home/page.tsx) (Home), [`app/settings/page.tsx`](https://github.com/mohamed-mudawi/blip/blob/main/app/settings/page.tsx) (Settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_root["App shell<br/>next entry<br/>[page.tsx]"]
  node_home_page["Home<br/>screen<br/>[page.tsx]"]
  node_login_page["Login<br/>screen<br/>[page.tsx]"]
  node_signup_page["Signup<br/>screen<br/>[page.tsx]"]
  node_settings_page["Settings<br/>screen<br/>[page.tsx]"]
  node_poster_ui["Poster<br/>composer"]
  node_topbar_ui["Top bar<br/>chrome<br/>[TopBar.tsx]"]
  node_usermenu_ui["User menu<br/>chrome<br/>[UserMenu.tsx]"]
end

subgraph group_backend["Backend"]
  node_upload_api["Uploads<br/>route handler<br/>[route.ts]"]
  node_health_api["Health<br/>route handler<br/>[route.ts]"]
  node_auth_callback["Auth callback<br/>callback route<br/>[route.ts]"]
end

subgraph group_integrations["Integrations"]
  node_ig_auth["Instagram auth<br/>oauth route<br/>[route.ts]"]
  node_ig_callback["IG callback<br/>oauth callback<br/>[route.ts]"]
  node_ig_status["IG status<br/>status route<br/>[route.ts]"]
  node_ig_post["IG post<br/>publish route<br/>[route.ts]"]
  node_ig_logout["IG logout<br/>disconnect route<br/>[route.ts]"]
  node_tw_auth["Twitter auth<br/>oauth route<br/>[route.ts]"]
  node_tw_callback["X callback<br/>oauth callback<br/>[route.ts]"]
  node_tw_status["X status<br/>status route<br/>[route.ts]"]
  node_tw_post["X post<br/>publish route<br/>[route.ts]"]
  node_tw_logout["X logout<br/>disconnect route<br/>[route.ts]"]
end

subgraph group_data["Data"]
  node_supabase_client["Supabase<br/>service client<br/>[supabase.ts]"]
  node_prisma_schema[("Prisma schema<br/>db schema<br/>[schema.prisma]")]
  node_uploads_store[("Uploads store<br/>media storage")]
end

subgraph group_external["External"]
  node_instagram_api(("Instagram API<br/>external service"))
  node_twitter_api(("Twitter/X API<br/>external service"))
  node_supabase_cloud(("Supabase cloud<br/>external service"))
end

node_app_root -->|"routes to"| node_home_page
node_app_root -->|"auth UI"| node_login_page
node_app_root -->|"auth UI"| node_signup_page
node_app_root -->|"routes to"| node_settings_page
node_home_page -->|"uses"| node_poster_ui
node_home_page -->|"uses"| node_topbar_ui
node_home_page -->|"uses"| node_usermenu_ui
node_poster_ui -->|"uploads media"| node_upload_api
node_poster_ui -->|"connects"| node_ig_auth
node_poster_ui -->|"connects"| node_tw_auth
node_poster_ui -->|"publishes"| node_ig_post
node_poster_ui -->|"publishes"| node_tw_post
node_settings_page -->|"checks"| node_ig_status
node_settings_page -->|"checks"| node_tw_status
node_ig_auth -->|"redirects"| node_ig_callback
node_ig_callback -->|"exchanges token"| node_instagram_api
node_ig_status -->|"reads state"| node_instagram_api
node_ig_post -->|"posts"| node_instagram_api
node_ig_logout -->|"disconnects"| node_instagram_api
node_tw_auth -->|"redirects"| node_tw_callback
node_tw_callback -->|"exchanges token"| node_twitter_api
node_tw_status -->|"reads state"| node_twitter_api
node_tw_post -->|"posts"| node_twitter_api
node_tw_logout -->|"disconnects"| node_twitter_api
node_upload_api -->|"stores"| node_uploads_store
node_upload_api -->|"persists metadata"| node_supabase_client
node_supabase_client -->|"connects"| node_supabase_cloud
node_prisma_schema -->|"models data"| node_supabase_client
node_auth_callback -->|"session callback"| node_supabase_cloud
node_health_api -->|"monitored by"| node_app_root

click node_app_root "https://github.com/mohamed-mudawi/blip/blob/main/app/page.tsx"
click node_home_page "https://github.com/mohamed-mudawi/blip/blob/main/app/home/page.tsx"
click node_login_page "https://github.com/mohamed-mudawi/blip/blob/main/app/login/page.tsx"
click node_signup_page "https://github.com/mohamed-mudawi/blip/blob/main/app/signup/page.tsx"
click node_settings_page "https://github.com/mohamed-mudawi/blip/blob/main/app/settings/page.tsx"
click node_poster_ui "https://github.com/mohamed-mudawi/blip/blob/main/app/components/SocialMediaPoster.tsx"
click node_topbar_ui "https://github.com/mohamed-mudawi/blip/blob/main/app/components/TopBar.tsx"
click node_usermenu_ui "https://github.com/mohamed-mudawi/blip/blob/main/app/components/UserMenu.tsx"
click node_upload_api "https://github.com/mohamed-mudawi/blip/blob/main/app/api/uploads/route.ts"
click node_health_api "https://github.com/mohamed-mudawi/blip/blob/main/app/api/health/route.ts"
click node_auth_callback "https://github.com/mohamed-mudawi/blip/blob/main/app/auth/callback/route.ts"
click node_ig_auth "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/route.ts"
click node_ig_callback "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/callback/route.ts"
click node_ig_status "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/status/route.ts"
click node_ig_post "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/post/route.ts"
click node_ig_logout "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/logout/route.ts"
click node_tw_auth "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/route.ts"
click node_tw_callback "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/callback/route.ts"
click node_tw_status "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/status/route.ts"
click node_tw_post "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/post/route.ts"
click node_tw_logout "https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/logout/route.ts"
click node_supabase_client "https://github.com/mohamed-mudawi/blip/blob/main/lib/supabase.ts"
click node_prisma_schema "https://github.com/mohamed-mudawi/blip/blob/main/prisma/schema.prisma"
click node_uploads_store "https://github.com/mohamed-mudawi/blip/tree/main/public/uploads"

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_root,node_home_page,node_login_page,node_signup_page,node_settings_page,node_poster_ui,node_topbar_ui,node_usermenu_ui toneBlue
class node_upload_api,node_health_api,node_auth_callback toneAmber
class node_ig_auth,node_ig_callback,node_ig_status,node_ig_post,node_ig_logout,node_tw_auth,node_tw_callback,node_tw_status,node_tw_post,node_tw_logout toneMint
class node_supabase_client,node_prisma_schema,node_uploads_store toneRose
class node_instagram_api,node_twitter_api,node_supabase_cloud toneIndigo
```

## Components

### Presentation

Browser-facing pages and shared UI

- [App shell](https://github.com/mohamed-mudawi/blip/blob/main/app/page.tsx): next entry · Root App Router entry and shared shell · `app/page.tsx`
- [Home](https://github.com/mohamed-mudawi/blip/blob/main/app/home/page.tsx): screen · Main logged-in landing screen · `app/home/page.tsx`
- [Login](https://github.com/mohamed-mudawi/blip/blob/main/app/login/page.tsx): screen · Sign-in screen · `app/login/page.tsx`
- [Signup](https://github.com/mohamed-mudawi/blip/blob/main/app/signup/page.tsx): screen · Account creation screen · `app/signup/page.tsx`
- [Settings](https://github.com/mohamed-mudawi/blip/blob/main/app/settings/page.tsx): screen · User configuration screen · `app/settings/page.tsx`
- [Poster](https://github.com/mohamed-mudawi/blip/blob/main/app/components/SocialMediaPoster.tsx): composer · Social posting workflow UI · `app/components/SocialMediaPoster.tsx`
- [Top bar](https://github.com/mohamed-mudawi/blip/blob/main/app/components/TopBar.tsx): chrome · Shared navigation/header · `app/components/TopBar.tsx`
- [User menu](https://github.com/mohamed-mudawi/blip/blob/main/app/components/UserMenu.tsx): chrome · Account menu and session actions · `app/components/UserMenu.tsx`

### Backend

Route handlers and callbacks

- [Uploads](https://github.com/mohamed-mudawi/blip/blob/main/app/api/uploads/route.ts): route handler · Receives and stores uploaded media · `app/api/uploads/route.ts`
- [Health](https://github.com/mohamed-mudawi/blip/blob/main/app/api/health/route.ts): route handler · Operational health check endpoint · `app/api/health/route.ts`
- [Auth callback](https://github.com/mohamed-mudawi/blip/blob/main/app/auth/callback/route.ts): callback route · Generic authentication redirect/callback boundary · `app/auth/callback/route.ts`

### Integrations

Platform-specific social posting flows

- [Instagram auth](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/route.ts): oauth route · Starts Instagram connection flow · `app/api/auth/instagram/route.ts`
- [IG callback](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/callback/route.ts): oauth callback · Handles Instagram OAuth return · `app/api/auth/instagram/callback/route.ts`
- [IG status](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/status/route.ts): status route · Checks Instagram connection state · `app/api/auth/instagram/status/route.ts`
- [IG post](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/post/route.ts): publish route · Publishes content to Instagram · `app/api/auth/instagram/post/route.ts`
- [IG logout](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/instagram/logout/route.ts): disconnect route · Disconnects Instagram account · `app/api/auth/instagram/logout/route.ts`
- [Twitter auth](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/route.ts): oauth route · Starts Twitter/X connection flow · `app/api/auth/twitter/route.ts`
- [X callback](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/callback/route.ts): oauth callback · Handles Twitter/X OAuth return · `app/api/auth/twitter/callback/route.ts`
- [X status](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/status/route.ts): status route · Checks Twitter/X connection state · `app/api/auth/twitter/status/route.ts`
- [X post](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/post/route.ts): publish route · Publishes content to Twitter/X · `app/api/auth/twitter/post/route.ts`
- [X logout](https://github.com/mohamed-mudawi/blip/blob/main/app/api/auth/twitter/logout/route.ts): disconnect route · Disconnects Twitter/X account · `app/api/auth/twitter/logout/route.ts`

### Data

Persistence and media storage

- [Supabase](https://github.com/mohamed-mudawi/blip/blob/main/lib/supabase.ts): service client · Backend service integration used by the app · `lib/supabase.ts`
- [Prisma schema](https://github.com/mohamed-mudawi/blip/blob/main/prisma/schema.prisma): db schema · Database models and persistence contract · `prisma/schema.prisma`
- [Uploads store](https://github.com/mohamed-mudawi/blip/tree/main/public/uploads): media storage · Publicly served uploaded files · `public/uploads`

### External

Third-party services

- **Instagram API**: external service · External Instagram/OAuth platform
- **Twitter/X API**: external service · External Twitter/X/OAuth platform
- **Supabase cloud**: external service · Hosted Supabase backend service

## Connections

- App shell → Home: routes to · App shell leads into the main app screen
- App shell → Login: auth UI · Entry path for sign-in
- App shell → Signup: auth UI · Entry path for account creation
- App shell → Settings: routes to · Shared app shell exposes settings
- Home → Poster: uses · Home screen centers on the posting workflow
- Home → Top bar: uses · Shared top navigation on the main screen
- Home → User menu: uses · Session/account controls
- Poster → Uploads: uploads media · Poster sends selected files to backend upload handling
- Poster → Instagram auth: connects · UI can initiate Instagram connection
- Poster → Twitter auth: connects · UI can initiate Twitter/X connection
- Poster → IG post: publishes · Posting workflow can target Instagram
- Poster → X post: publishes · Posting workflow can target Twitter/X
- Settings → IG status: checks · Settings likely shows Instagram connection state
- Settings → X status: checks · Settings likely shows Twitter/X connection state
- Instagram auth → IG callback: redirects · Instagram OAuth returns through callback
- IG callback → Instagram API: exchanges token · Callback completes against Instagram
- IG status → Instagram API: reads state · Connection state is derived from Instagram integration data
- IG post → Instagram API: posts · Content is published through Instagram API
- IG logout → Instagram API: disconnects · Terminates Instagram linkage
- Twitter auth → X callback: redirects · Twitter/X OAuth returns through callback
- X callback → Twitter/X API: exchanges token · Callback completes against Twitter/X
- X status → Twitter/X API: reads state · Connection state is derived from Twitter/X integration data
- X post → Twitter/X API: posts · Content is published through Twitter/X API
- X logout → Twitter/X API: disconnects · Terminates Twitter/X linkage
- Uploads → Uploads store: stores · Uploaded media is made available as public files
- Uploads → Supabase: persists metadata · Upload flow can record state through backend services
- Supabase → Supabase cloud: connects · Client-side helper talks to hosted Supabase
- Prisma schema → Supabase: models data · Schema defines the structured data used by the app
- Auth callback → Supabase cloud: session callback · Generic auth callback completes with backend identity/session support
- Health → App shell: monitored by · Health endpoint supports deployment checks for the app