gaurangrshah/plura

1. Overall shape

- This is a Next.js 14 App Router monorepo-style application organized around three user-facing surfaces: a public marketing site, a multi-tenant authenticated dashboard, and public domain-based pages for funnels/content.

- The app is heavily componentized, with most business features implemented in route-local components under app/ and shared UI/forms under components/.

2. Route partitioning is the top-level boundary

- app/site contains the public marketing site.

- app/(main) contains the authenticated product UI.

- app/[domain]/[path] is a runtime-resolved public route for tenant-owned pages, likely used for funnel pages or branded content on custom domains/subdomains.

- This route split is important for architecture diagrams because it separates public web traffic, logged-in dashboard traffic, and tenant-hosted public pages.

3. Multi-tenant domain model

- The dashboard is split into two major tenant scopes:

- app/(main)/agency/[agencyId] for agency-level administration

- app/(main)/subaccount/[subaccountId] for client/sub-account operations

- The agency layer manages higher-order concerns like team, billing, subaccounts, launchpad, and settings.

- The subaccount layer manages operational features like contacts, pipelines, funnels, media, workflows, and settings.

- This is the core business boundary: agency owns and administers multiple subaccounts.

4. Authentication and access control

- The repo uses Clerk for auth, with routes for sign-in/sign-up under app/(main)/agency/(auth).

- middleware.ts indicates request-time protection and route gating, which is a key runtime boundary.

- There is a dedicated unauthorized screen at app/(main)/agency/unauthorized and a shared unauthorized component in components/unauthorized.

- For a diagram, auth should be shown as an edge/request gate in front of protected dashboard routes.

5. Data layer and persistence

- Data access is centered in lib/db.ts, lib/queries.ts, lib/constants.ts, and lib/types.ts.

- Persistence uses Prisma with prisma/schema.prisma, and the README states the backend uses SQLite locally and Turso/libsql in production.

- This means the architecture has a single database boundary serving all core product domains: agencies, subaccounts, funnels, workflows, pipelines, contacts, billing metadata, and media records.

6. Payments and billing subsystem

- Billing is isolated under app/(main)/agency/[agencyId]/billing.

- Stripe integration is split between:

- client/server helpers in lib/stripe/*

- API routes in app/api/stripe/*

- billing UI components such as pricing-card.tsx and subscription-helper.tsx

- Data flow here is: billing UI → Stripe action/API route → Stripe service → webhook → database update.

- This is a distinct external-service boundary and should be shown separately from the main app database flow.

7. File uploads and media subsystem

- UploadThing is exposed through app/api/uploadthing/* and configured in lib/uploadthing.ts.

- The user-facing media area lives at app/(main)/subaccount/[subaccountId]/media, with shared media components in components/media.

- This is another external boundary: dashboard UI → UploadThing API → stored assets → media library UI.

8. Funnel builder is a major product subsystem

- Funnel management lives under app/(main)/subaccount/[subaccountId]/funnels.

- The funnel editor is nested deeply under funnels/[funnelId]/editor/[funnelPageId] and is composed of:

- a central editor canvas

- a sidebar with tabs for components/layers/media/settings

- recursive render components for page elements

- The funnel editor supports element types like container, two-column layout, text, link, video, checkout, and contact form, indicating a block-based page builder.

- This subsystem should be diagrammed as a structured content editor backed by the database.

9. Workflow automation subsystem

- Workflows live under app/(main)/subaccount/[subaccountId]/workflows.

- The editor uses provider-based state and dedicated UI pieces:

- canvas

- sidebar

- toolbar

- node settings

- workflow nodes

- There is a small action layer in workflows/_actions/workflow-actions.ts, suggesting server-side mutations for workflow creation/update.

- This is a separate builder from funnels: funnels are for page composition, workflows are for automation logic.

10. Pipeline / CRM subsystem

- Pipelines are implemented under app/(main)/subaccount/[subaccountId]/pipelines.

- The feature uses lane/ticket/view/settings components, which implies a kanban-style deal or lead pipeline.

- Contacts live separately under contacts, and there are forms for tickets and contacts, so the likely flow is contacts and leads feed pipeline tickets.

- In a diagram, pipelines should be shown as the operational CRM layer connected to subaccount data.

11. Agency administration features

- Agency-level pages cover team, billing, all-subaccounts, launchpad, and settings.

- Shared forms such as invitation, agency details, subaccount details, and subscription forms support these admin flows.

- This layer is where an agency manages tenants, users, and paid plan state rather than end-customer operations.

12. Shared UI and composition model

- components/ui is a large shadcn/ui-style base layer used across the app.

- Feature-specific shared components live in components/forms, components/global, components/sidebar, components/media, and components/site.

- The repo uses reusable provider wrappers in providers/ for theme, modals, workflow editor state, and editor actions.

- This indicates a design where route pages are thin shells and most interactive behavior is delegated to shared component systems.

13. Runtime and deployment concerns

- The app runs on Next.js/Vercel, with vercel.json controlling the build command and Sentry configs present for client/edge/server error reporting.

- instrumentation.ts suggests app-level runtime instrumentation is enabled.

- Because auth middleware and public-domain routing are part of the request path, edge/runtime behavior matters to the system architecture.

14. What to show in an architecture diagram

- The most important boxes are:

- public site

- auth gate/middleware

- agency dashboard

- subaccount dashboard

- public domain page renderer

- Prisma/Turso database

- Stripe

- UploadThing

- funnel editor

- workflow editor

- pipeline/contacts CRM

- The key arrows are:

- browser/request → middleware → route group

- route group → server components/actions/queries → database

- billing UI → Stripe → webhook → database

- media UI → UploadThing → stored assets

- editors → provider state + database-backed persistence