mohamed-mudawi/blip

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.