Architecture

Folder Structure

Where everything lives. Memorise the highlighted folders — that's where 95% of your work happens.

Top level

text

coreboard/
├── src/
│   ├── app/                # Next.js App Router pages + API routes
│   ├── components/         # Reusable React components
│   ├── lib/                # Server-side helpers (Supabase, Google clients)
│   └── middleware.ts       # Auth gate for every request
├── supabase/               # Schema and SQL migration patches
├── public/                 # Static assets
├── .env.example            # Required environment variables
├── eslint.config.mjs       # Lint rules
├── next.config.ts          # Next.js config
├── package.json            # Dependencies and scripts
└── tsconfig.json           # TypeScript config (strict mode)

src/app/

Routes are file-based. Every folder with a page.tsx becomes a public URL.

text

src/app/
├── layout.tsx              # Root HTML, theme class, fonts
├── page.tsx                # Redirects to /dashboard or /login
├── globals.css             # Tailwind import, theme tokens, base styles
├── login/                  # Public login page
├── auth/callback/          # Supabase email confirmation handler
├── dashboard/              # Authenticated agency surface
│   ├── layout.tsx          # 3-column shell: Sidebar | content | InsightsPanel
│   ├── page.tsx            # Client list (admin) or single-client redirect (client)
│   ├── clients/
│   │   ├── new/            # Admin-only "create client" form
│   │   └── [id]/
│   │       ├── page.tsx    # Renders <ClientDashboard /> for one client
│   │       └── edit/       # Admin-only edit form
│   └── settings/           # User profile + integration toggles
├── documentation/          # ← You are here. Static docs site.
└── api/                    # Server route handlers (see API Routes page)

src/components/

text

src/components/
├── dashboard/              # The big one — ClientDashboard.tsx + every chart
│   ├── ClientDashboard.tsx       # 1,200+ lines. The screen the user sees.
│   ├── DateRangePicker.tsx       # Global date control
│   ├── TrafficChart.tsx          # GA4 line chart
│   ├── SessionsByChannelChart.tsx
│   ├── KeywordClicksChart.tsx
│   ├── PipelineRatesChart.tsx    # Used inside Pipeline Overview
│   ├── PipelineStagesChart.tsx
│   ├── PlaceholderChart.tsx      # Empty-state component for charts
│   └── HistoricalRevenueSection.tsx  # RFMS sheet integration
├── portal/                 # Client Portal sub-tabs
│   ├── ClientPortalTab.tsx       # Hosts all sub-tabs and their editors
│   ├── sections/                  # Read-only renderers
│   │   ├── SummarySection.tsx
│   │   ├── PipelineSection.tsx    # Pipeline Overview, lives inside the portal
│   │   ├── SnapshotSection.tsx
│   │   ├── ScorecardSection.tsx
│   │   ├── GamePlanSection.tsx
│   │   ├── DeliverablesSection.tsx
│   │   ├── KpiReportingSection.tsx
│   │   ├── ContentTrackerSection.tsx
│   │   └── DocumentsSection.tsx
│   └── editors/                   # Modal editors used only by admin
│       └── (one per editable section)
├── reports/                # PDF components
│   ├── MonthlyReportPDF.tsx       # The full report
│   └── PDFDownloadButton.tsx      # Client-side download trigger
├── integrations/           # Connect popup (admin only)
│   └── IntegrationPanel.tsx
├── Sidebar.tsx             # Left dashboard nav (client list)
├── InsightsPanel.tsx       # Right-rail panel (announcements, AI insights)
└── SubmitRequestModal.tsx  # Client → agency request form

src/lib/

text

src/lib/
├── supabase/
│   ├── client.ts           # Browser client — used in 'use client' files
│   ├── server.ts           # Server client (cookie-aware) — used in route handlers, RSC
│   └── middleware.ts       # Refreshes Supabase session cookies on every request
├── google/                 # Google API helpers and OAuth utilities
├── ghl/                    # GoHighLevel API helpers
└── types/                  # Shared TypeScript types (e.g. portal section schemas)

Supabase client choice matters

Use the wrong Supabase factory and you will silently break sessions or leak credentials. The rule:

Server Components, route handlers, server actions → @/lib/supabase/server.
'use client' components → @/lib/supabase/client.
Middleware → @/lib/supabase/middleware (already wired, do not duplicate).

supabase/

text

supabase/
├── schema.sql                          # Source of truth — the full schema
├── fix-profile-trigger.sql             # Patch: auth.users → profiles trigger
├── update-clients-schema.sql           # Patch: clients columns
├── update-integrations-schema.sql      # Patch: integrations columns
├── add-youtube-field.sql               # Patch: clients.youtube_channel_id
├── add-gbp-place-id.sql                # Patch: clients.gbp_place_id
└── add-XXX.sql                         # Add new patch files here for new columns

Files you will read most often

src/components/dashboard/ClientDashboard.tsx — the dashboard screen.
src/components/portal/ClientPortalTab.tsx — the portal host.
src/components/portal/sections/PipelineSection.tsx — pipeline view.
src/app/api/metrics/ghl/route.ts — pipeline metrics aggregation.
src/app/api/metrics/ga4/route.ts — the simplest API route to learn from.
supabase/schema.sql — every column we read or write.

PreviousTech Stack Next Data Flow