# anil-matcha/free-ai-social-media-scheduler architecture

> Architecture diagram of the GitHub repository anil-matcha/free-ai-social-media-scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anil-matcha/free-ai-social-media-scheduler
- Repository: https://github.com/anil-matcha/free-ai-social-media-scheduler

## Overview

1. **Overall shape**
   - This is a single Next.js 16 application, not a split frontend/backend repo.
   - The architecture centers on the Next.js App Router for pages plus `src/app/api` route handlers for all server-side operations.

2. **User-facing surface**
   - Public/primary pages live under `src/app`: landing (`page.js`), login, pricing, gallery, and integrations.
   - `layout.js`, `providers.js`, `Navbar.js`, and `Footer.js` provide the shared shell and client-side context for the app.

3. **Server API boundary**
   - All backend capabilities are exposed as route handlers in `src/app/api`.
   - The main functional groups are:
     - authentication: `api/auth/[...nextauth]`
     - posts: `api/posts`
     - uploads/downloads: `api/upload`, `api/download`
     - social accounts: `api/social/accounts`, `api/social/youtube/connect`
     - billing/checkout: `api/checkout`, `api/stripe/checkout`, `api/stripe/webhook`, `api/webhook/stripe`
   - This keeps the browser-facing UI thin and pushes business logic into API endpoints.

4. **Persistence layer**
   - PostgreSQL is the durable store, accessed through Prisma.
   - `prisma/schema.prisma` defines the data model, and `src/lib/prisma.js` centralizes the DB client.
   - Based on the feature set, the core persisted entities are users, scheduled posts, connected social accounts, and billing/credit records.

5. **Auth and session management**
   - Authentication is handled by NextAuth.js with Google OAuth.
   - `src/lib/auth.js` encapsulates auth configuration and is consumed by the NextAuth route.
   - The app likely uses authenticated sessions to gate account management, posting, and billing workflows.

6. **Billing and credits**
   - Stripe is the payment layer for purchasing credits.
   - Checkout flows go through dedicated API routes, and Stripe webhooks are used to reconcile completed payments back into the app’s database state.
   - `src/lib/stripe.js` and `src/lib/services/billing.js` suggest a thin integration wrapper plus business logic for credit issuance and payment handling.

7. **Social platform connectivity**
   - The product supports YouTube and TikTok posting, with multi-account management.
   - `api/social/accounts` handles listing and CRUD-style account management, while `api/social/youtube/connect` is a dedicated OAuth/connect flow for YouTube.
   - This is the boundary where external platform credentials and account metadata are stored and associated with the user.

8. **Publishing and media workflow**
   - The app is video-first: users provide media URLs, choose platform-specific options, and schedule publishing.
   - `api/posts` is the main post lifecycle API, and `api/upload` / `api/download` handle media acquisition or transfer.
   - The repo description references MuAPI, so publishing and media processing likely depend on that external service rather than an in-repo worker.

9. **Asynchronous and event-driven paths**
   - Webhook endpoints are a key part of the architecture, especially for Stripe.
   - There are webhook routes under both `api/stripe/webhook` and `api/webhook/stripe`, suggesting webhook handling is a distinct integration boundary and possibly includes compatibility or aliasing.
   - Long-running or externally triggered state changes appear to flow back into the app through these handlers rather than through a separate job service.

10. **Shared backend services**
   - `src/lib/services/user.js` and `src/lib/services/billing.js` act as the domain/service layer between route handlers and Prisma.
   - This is the main place where business rules are likely centralized, keeping API routes mostly orchestration-focused.
   - `src/lib/config.js` likely standardizes environment-driven settings for external services and runtime behavior.

11. **External dependencies that materially shape the design**
   - NextAuth/Google OAuth handles identity, Stripe handles monetization, PostgreSQL/Prisma handles persistence, and MuAPI handles media/publishing integration.
   - Because the app is self-hostable and described as a “single Next.js app,” there is no evidence of separate microservices, message brokers, or dedicated worker infrastructure in this repo.

12. **How data moves through the system**
   - Browser → Next.js page/UI → API route → service layer → Prisma/PostgreSQL for durable state.
   - For external side effects: API route → Stripe/MuAPI/social platform → webhook callback or account-connect route → service layer → database update.
   - That split between synchronous UI requests and webhook-driven reconciliation is the key architectural pattern to diagram.

Main entry points: [`src/lib/prisma.js`](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/prisma.js) (Prisma client), [`src/app/layout.js`](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/layout.js) (Layout), [`src/lib/services/billing.js`](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/services/billing.js) (Billing service), [`src/lib/config.js`](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/config.js) (Config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app_shell["App shell"]
  node_page_home["Home<br/>Next page<br/>[page.js]"]
  node_page_login["Login<br/>Next page<br/>[page.js]"]
  node_page_pricing["Pricing<br/>Next page<br/>[page.js]"]
  node_page_gallery["Gallery<br/>Next page<br/>[page.js]"]
  node_page_integrations["Integrations<br/>Next page<br/>[page.js]"]
  node_layout_shell["Layout<br/>[layout.js]"]
  node_providers["Providers<br/>Client context<br/>[providers.js]"]
  node_navbar["Navbar<br/>UI component<br/>[Navbar.js]"]
  node_footer["Footer<br/>UI component<br/>[Footer.js]"]
end

subgraph group_api_boundary["API routes"]
  node_api_auth["Auth API<br/>NextAuth route<br/>[route.js]"]
  node_api_posts["Posts API<br/>Post CRUD<br/>[route.js]"]
  node_api_post_item["Post item<br/>Post detail<br/>[route.js]"]
  node_api_social_accounts["Accounts API<br/>Social accounts<br/>[route.js]"]
  node_api_social_account_item["Account item<br/>Social account detail<br/>[route.js]"]
  node_api_youtube_connect["YouTube connect<br/>OAuth connect<br/>[route.js]"]
  node_api_upload["Upload API<br/>Media transfer<br/>[route.js]"]
  node_api_download["Download API<br/>Media fetch<br/>[route.js]"]
  node_api_checkout["Checkout API<br/>Billing entry<br/>[route.js]"]
  node_api_stripe_checkout["Stripe checkout<br/>Stripe route<br/>[route.js]"]
  node_api_stripe_webhook["Stripe webhook<br/>Webhook route<br/>[route.js]"]
  node_api_webhook_stripe["Webhook alias<br/>Webhook route<br/>[route.js]"]
end

subgraph group_domain_layer["Domain services"]
  node_lib_auth["Auth config<br/>[auth.js]"]
  node_lib_billing["Billing service<br/>Domain service<br/>[billing.js]"]
  node_lib_user["User service<br/>Domain service<br/>[user.js]"]
  node_lib_stripe["Stripe client<br/>Payments client<br/>[stripe.js]"]
  node_lib_config["Config<br/>[config.js]"]
end

subgraph group_data_layer["Data layer"]
  node_lib_prisma["Prisma client<br/>DB client<br/>[prisma.js]"]
  node_schema["Schema<br/>[schema.prisma]"]
end

node_page_home -->|"renders in"| node_layout_shell
node_page_login -->|"renders in"| node_layout_shell
node_page_pricing -->|"renders in"| node_layout_shell
node_page_gallery -->|"renders in"| node_layout_shell
node_page_integrations -->|"renders in"| node_layout_shell
node_layout_shell -->|"wraps"| node_providers
node_layout_shell -->|"includes"| node_navbar
node_layout_shell -->|"includes"| node_footer
node_api_auth -->|"uses"| node_lib_auth
node_api_auth -->|"uses"| node_lib_prisma
node_api_posts -->|"uses"| node_lib_prisma
node_api_post_item -->|"uses"| node_lib_prisma
node_api_social_accounts -->|"uses"| node_lib_prisma
node_api_social_account_item -->|"uses"| node_lib_prisma
node_api_youtube_connect -->|"uses"| node_lib_auth
node_api_youtube_connect -->|"uses"| node_lib_prisma
node_api_upload -->|"uses"| node_lib_config
node_api_download -->|"uses"| node_lib_config
node_api_checkout -->|"uses"| node_lib_billing
node_api_checkout -->|"uses"| node_lib_stripe
node_api_stripe_checkout -->|"uses"| node_lib_stripe
node_api_stripe_webhook -->|"uses"| node_lib_billing
node_api_webhook_stripe -->|"uses"| node_lib_billing
node_lib_billing -->|"uses"| node_lib_prisma
node_lib_user -->|"uses"| node_lib_prisma
node_lib_auth -->|"uses"| node_lib_config
node_lib_stripe -->|"uses"| node_lib_config
node_lib_prisma -->|"implements"| node_schema

click node_page_home "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/page.js"
click node_page_login "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/login/page.js"
click node_page_pricing "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/pricing/page.js"
click node_page_gallery "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/gallery/page.js"
click node_page_integrations "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/integrations/page.js"
click node_layout_shell "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/layout.js"
click node_providers "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/providers.js"
click node_navbar "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/components/Navbar.js"
click node_footer "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/components/Footer.js"
click node_api_auth "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/auth/[...nextauth]/route.js"
click node_api_posts "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/posts/route.js"
click node_api_post_item "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/posts/[id]/route.js"
click node_api_social_accounts "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/social/accounts/route.js"
click node_api_social_account_item "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/social/accounts/[id]/route.js"
click node_api_youtube_connect "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/social/youtube/connect/route.js"
click node_api_upload "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/upload/route.js"
click node_api_download "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/download/route.js"
click node_api_checkout "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/checkout/route.js"
click node_api_stripe_checkout "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/stripe/checkout/route.js"
click node_api_stripe_webhook "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/stripe/webhook/route.js"
click node_api_webhook_stripe "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/webhook/stripe/route.js"
click node_lib_auth "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/auth.js"
click node_lib_billing "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/services/billing.js"
click node_lib_user "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/services/user.js"
click node_lib_prisma "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/prisma.js"
click node_schema "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/prisma/schema.prisma"
click node_lib_stripe "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/stripe.js"
click node_lib_config "https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/config.js"

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_page_home,node_page_login,node_page_pricing,node_page_gallery,node_page_integrations,node_layout_shell,node_providers,node_navbar,node_footer toneBlue
class node_api_auth,node_api_posts,node_api_post_item,node_api_social_accounts,node_api_social_account_item,node_api_youtube_connect,node_api_upload,node_api_download,node_api_checkout,node_api_stripe_checkout,node_api_stripe_webhook,node_api_webhook_stripe toneAmber
class node_lib_auth,node_lib_billing,node_lib_user,node_lib_stripe,node_lib_config toneMint
class node_lib_prisma,node_schema toneRose
```

## Components

### App shell

Shared Next.js UI structure and public pages

- [Home](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/page.js): Next page · Landing page · `src/app/page.js`
- [Login](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/login/page.js): Next page · Authentication entry page · `src/app/login/page.js`
- [Pricing](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/pricing/page.js): Next page · Plan and credits page · `src/app/pricing/page.js`
- [Gallery](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/gallery/page.js): Next page · Media showcase page · `src/app/gallery/page.js`
- [Integrations](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/integrations/page.js): Next page · Connected services page · `src/app/integrations/page.js`
- [Layout](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/layout.js): App layout · Shared app frame · `src/app/layout.js`
- [Providers](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/providers.js): Client context · Global client-side wrappers · `src/app/providers.js`
- [Navbar](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/components/Navbar.js): UI component · Top navigation · `src/components/Navbar.js`
- [Footer](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/components/Footer.js): UI component · Site footer · `src/components/Footer.js`

### API routes

Route handlers that expose all server-side capabilities

- [Auth API](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/auth/[...nextauth]/route.js): NextAuth route · Google OAuth and session handling · `src/app/api/auth/[...nextauth]/route.js`
- [Posts API](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/posts/route.js): Post CRUD · Create, update, and manage scheduled posts · `src/app/api/posts/route.js`
- [Post item](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/posts/[id]/route.js): Post detail · Single post operations · `src/app/api/posts/[id]/route.js`
- [Accounts API](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/social/accounts/route.js): Social accounts · Manage connected social accounts · `src/app/api/social/accounts/route.js`
- [Account item](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/social/accounts/[id]/route.js): Social account detail · Single account operations · `src/app/api/social/accounts/[id]/route.js`
- [YouTube connect](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/social/youtube/connect/route.js): OAuth connect · YouTube account linking flow · `src/app/api/social/youtube/connect/route.js`
- [Upload API](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/upload/route.js): Media transfer · Media upload or ingestion · `src/app/api/upload/route.js`
- [Download API](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/download/route.js): Media fetch · Media retrieval or transfer · `src/app/api/download/route.js`
- [Checkout API](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/checkout/route.js): Billing entry · Checkout orchestration · `src/app/api/checkout/route.js`
- [Stripe checkout](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/stripe/checkout/route.js): Stripe route · Stripe checkout session creation · `src/app/api/stripe/checkout/route.js`
- [Stripe webhook](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/stripe/webhook/route.js): Webhook route · Stripe event reconciliation · `src/app/api/stripe/webhook/route.js`
- [Webhook alias](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/app/api/webhook/stripe/route.js): Webhook route · Alternate Stripe webhook entry · `src/app/api/webhook/stripe/route.js`

### Domain services

Shared auth, billing, and user logic

- [Auth config](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/auth.js): NextAuth config · Auth provider and session setup · `src/lib/auth.js`
- [Billing service](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/services/billing.js): Domain service · Credit and payment business rules · `src/lib/services/billing.js`
- [User service](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/services/user.js): Domain service · User-focused business rules · `src/lib/services/user.js`
- [Stripe client](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/stripe.js): Payments client · Stripe integration wrapper · `src/lib/stripe.js`
- [Config](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/config.js): Runtime config · Environment and runtime settings · `src/lib/config.js`

### Data layer

Database schema and Prisma client

- [Prisma client](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/src/lib/prisma.js): DB client · Centralized database access · `src/lib/prisma.js`
- [Schema](https://github.com/anil-matcha/free-ai-social-media-scheduler/blob/main/prisma/schema.prisma): Prisma schema · Persistent data model · `prisma/schema.prisma`

## Connections

- Home → Layout: renders in · Home page uses the shared app layout
- Login → Layout: renders in · Login page uses the shared app layout
- Pricing → Layout: renders in · Pricing page uses the shared app layout
- Gallery → Layout: renders in · Gallery page uses the shared app layout
- Integrations → Layout: renders in · Integrations page uses the shared app layout
- Layout → Providers: wraps · Layout mounts client providers
- Layout → Navbar: includes · Shared navigation is part of the shell
- Layout → Footer: includes · Shared footer is part of the shell
- Auth API → Auth config: uses · NextAuth route consumes auth configuration
- Auth API → Prisma client: uses · Auth state reads and writes through Prisma
- Posts API → Prisma client: uses · Posts API persists post state
- Post item → Prisma client: uses · Single post operations hit the database
- Accounts API → Prisma client: uses · Account management persists connections
- Account item → Prisma client: uses · Single account operations hit the database
- YouTube connect → Auth config: uses · YouTube connect relies on auth context
- YouTube connect → Prisma client: uses · Connected account metadata is persisted
- Upload API → Config: uses · Upload behavior is environment-driven
- Download API → Config: uses · Download behavior is environment-driven
- Checkout API → Billing service: uses · Checkout orchestrates billing logic
- Checkout API → Stripe client: uses · Checkout creates Stripe flows
- Stripe checkout → Stripe client: uses · Stripe checkout route uses payment client
- Stripe webhook → Billing service: uses · Webhook reconciles payments through billing logic
- Webhook alias → Billing service: uses · Alias webhook also reconciles payments
- Billing service → Prisma client: uses · Billing state is stored in the database
- User service → Prisma client: uses · User service reads and writes persistent data
- Auth config → Config: uses · Auth setup is configuration-driven
- Stripe client → Config: uses · Stripe client is configuration-driven
- Prisma client → Schema: implements · Prisma client is generated from schema