How anil-matcha/free-ai-social-media-scheduler works
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: prisma.js Prisma client · layout.js Layout · billing.js Billing service · config.js Config
Components 28
App shell
Shared Next.js UI structure and public pages
- Home · Landing page
src/app/page.js - Login · Authentication entry page
src/app/login/page.js - Pricing · Plan and credits page
src/app/pricing/page.js - Gallery · Media showcase page
src/app/gallery/page.js - Integrations · Connected services page
src/app/integrations/page.js - Layout · Shared app frame
src/app/layout.js - Providers · Global client-side wrappers
src/app/providers.js - Navbar · Top navigation
src/components/Navbar.js - Footer · Site footer
src/components/Footer.js
API routes
Route handlers that expose all server-side capabilities
- Auth API · Google OAuth and session handling
src/app/api/auth/[...nextauth]/route.js - Posts API · Create, update, and manage scheduled posts
src/app/api/posts/route.js - Post item · Single post operations
src/app/api/posts/[id]/route.js - Accounts API · Manage connected social accounts
src/app/api/social/accounts/route.js - Account item · Single account operations
src/app/api/social/accounts/[id]/route.js - YouTube connect · YouTube account linking flow
src/app/api/social/youtube/connect/route.js - Upload API · Media upload or ingestion
src/app/api/upload/route.js - Download API · Media retrieval or transfer
src/app/api/download/route.js - Checkout API · Checkout orchestration
src/app/api/checkout/route.js - Stripe checkout · Stripe checkout session creation
src/app/api/stripe/checkout/route.js - Stripe webhook · Stripe event reconciliation
src/app/api/stripe/webhook/route.js - Webhook alias · Alternate Stripe webhook entry
src/app/api/webhook/stripe/route.js
Domain services
Shared auth, billing, and user logic
- Auth config · Auth provider and session setup
src/lib/auth.js - Billing service · Credit and payment business rules
src/lib/services/billing.js - User service · User-focused business rules
src/lib/services/user.js - Stripe client · Stripe integration wrapper
src/lib/stripe.js - Config · Environment and runtime settings
src/lib/config.js
Data layer
Database schema and Prisma client
- Prisma client · Centralized database access
src/lib/prisma.js - Schema · Persistent data model
prisma/schema.prisma
Connections 28
- 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