Social0 Frontend — Developer Documentation

This folder contains per-page documentation for the Next.js app router frontend. Each doc describes route, purpose, access, data flow, components, state, business logic, URL params, error states, and related pages.

---

Documented pages

---

High-level architecture

Auth flow

• Session: Server uses auth.api.getSession({ headers }) (from @/lib/auth). Client uses useSession() from @/lib/auth-client where needed (e.g. landing header).
• Sign-in: /auth — email+password via signIn.email(), Google via signIn.social({ provider: "google" }). Callback URL is /dashboard/composer.
• Sign-up: POST to /api/auth/sign-up or sign-up-with-turnstile; optional Turnstile when NEXT_PUBLIC_TURNSTILE_SITE_KEY is set. Success often redirects to /auth/verify-email?email=....
• Verify email: 6-digit OTP via authClient.emailOtp.verifyEmail; success → /onboarding.
• Password reset: Forgot password requests OTP; reset-password page submits OTP + new password; success → /auth?reset=success.
• Protected routes: Dashboard pages typically redirect to / or /auth when there is no session. Some (e.g. billing, bulk-tools) redirect to /dashboard/billing?upgrade=1 when plan does not allow the feature.

Data layer

• Database: Drizzle ORM (@/db, @/db/schema). Main entities: user, userSettings, account, connectedAccounts, posts, postPublications, mediaUploads, resurfaceSchedules, autoPlugs, queuedPosts, etc.
• Server actions: @/app/actions/ — settings (getUserSettingsSnapshot, updateDisplayName, updateUserImage, updateAutomationEmails, updatePlatformPreferences, updateTimezone, signOutAllDevices, updateConnectionAvatar), onboarding (getOnboardingStatus, setOnboardingGoal, setOnboardingCompleted), posts, publish, resurface.
• List data: Post list and filters live in app/dashboard/posts/posts-list-data.ts — getPostsListData, getPostDetail, getPostForEdit, getPostMedia, getQueuedSlotForPost, hasPaymentFailedPosts. Used by posts, scheduled, drafts, posted, and post detail/edit.
• Subscription / limits: @/lib/subscription (getSubscriptionForUser), @/lib/plan-limits (checkAccountLimits, checkTwitterTweetLimit, checkBulkToolsAllowed), @/lib/plans (getPlanLimits, SubscriptionTier, isActiveTier).

Key patterns

• Composer → Create: User drafts in Composer (client state); on "Continue", payload is stored via setComposerPayload() and user is sent to /dashboard/create/[slug]?fromComposer=1. Create forms call consumeComposerPayload() to prefill and clear in effect cleanup.
• Post status derivation: List and detail pages may correct posts stuck in "publishing" when all publications have finished (set to "published" or "partial" in DB). Effective status can differ from raw posts.status for display.
• Queue: No dedicated /dashboard/queue page. Queue is managed via Settings (Queue tab), SchedulePostSidebar in create flow, and queue API routes (/api/queue/*). Scheduled posts with a pending queued_posts row show "Queued" on list/detail.
• Token health: runTokenHealthCheckForUser and token status/expiry drive connection list and create-form account display. Some platforms (e.g. YouTube, TikTok) skip expiry display; others show expiring_soon / expired.
• Content types: @/lib/content-types defines slugs (text, image, video, threads, collection) and supported platform ids per type. Create forms are chosen by slug in /dashboard/create/[type].

---

Glossary

Post statuses (posts table)

Publication status (post_publications)

• published, failed, pending, etc. — per-platform outcome. Used for badges and "Retry" on post detail.

Subscription tiers (plans)

Plan IDs come from env: DODO_PAYMENTS_STARTER_PRODUCT_ID, etc. Limits in @/lib/plans and @/lib/plan-limits.

Platform identifiers (lib/platforms / content-types)

• linkedin, facebook, bluesky, youtube, pinterest, instagram, tiktok, twitter_x, threads. Used in OAuth, connections, and content-type platform allowlists.

Content type slugs (create flow)

• text — Text post (plain text).
• image — Image post (with optional caption).
• video — Video post.
• threads — Multi-post thread (Twitter/Threads/Bluesky).
• collection — Collection of images/videos in one post (e.g. carousel).

Date/time

• User preferences: use24HourTimeFormat, dateFormat (dd/MM/yyyy | MM/dd/yyyy | yyyy-MM-dd), timezone (e.g. UTC). Stored in userSettings, read via getUserSettingsSnapshot().

Other

• Resurface: Re-post or boost a post (e.g. Twitter) on a schedule; gated by plan (allowResurface).
• Auto-plug: Automatically add a plug/comment to high-performing posts; gated by plan (allowAutoPlug).
• Queued post: A scheduled post that has a row in queued_posts with status "pending" and is assigned to a queue slot.