File System Architecture

2.1 Top-Level Structure

sites/dashboard/
├── app/                    # Next.js App Router (pages + APIs)
├── lib/                    # Shared utilities, database, business logic
├── database/               # Schema, migrations, SQLite files
├── types/                  # TypeScript type definitions
├── data/                   # JSON data files (mock data, seed data)
├── docs/                   # Documentation (internal)
├── scripts/                # Utility scripts (add users, migrations)
├── public/                 # Static assets (images, fonts)
├── .env.local              # Environment variables (NEVER COMMIT)
├── middleware.ts           # Auth middleware (runs on every request)
└── next.config.js          # Next.js configuration

2.2 The app/ Directory (Heart of the Application)

This is where routing happens. Next.js uses file-system based routing.

app/
├── page.tsx                # Homepage (/) - redirects to role-based route
├── layout.tsx              # Root layout (wraps ALL pages)
├── middleware.ts           # Request interceptors
│
├── (admin)/                # Admin portal route group
│   └── admin/
│       ├── page.tsx        # /admin (redirects to dashboard)
│       ├── layout.tsx      # Admin layout (sidebar)
│       ├── dashboard/      # /admin/dashboard
│       ├── clients/        # /admin/clients
│       ├── billing/        # /admin/billing/*
│       ├── services/       # /admin/services/*
│       ├── staff/          # /admin/staff
│       ├── audit-logs/     # /admin/audit-logs
│       ├── operations/     # /admin/operations
│       ├── analytics/      # /admin/analytics
│       └── acquisition/    # /admin/acquisition
│
├── (client)/               # Client portal route group
│   ├── dashboard/          # /dashboard
│   ├── ai-receptionist/    # /ai-receptionist
│   ├── seo-bot/            # /seo-bot
│   ├── automations/        # /automations
│   ├── website/            # /website
│   ├── appointments/       # /appointments
│   ├── analytics/          # /analytics
│   ├── settings/           # /settings
│   └── support/            # /support
│
├── sales/                  # Sales dashboard
│   ├── page.tsx            # /sales (main dashboard)
│   ├── layout.tsx          # Sales layout
│   ├── pipeline/           # /sales/pipeline
│   ├── leads/              # /sales/leads
│   ├── clients/            # /sales/clients
│   ├── activities/         # /sales/activities
│   ├── commission/         # /sales/commission
│   ├── demo/               # /sales/demo
│   └── docs/               # /sales/docs
│
├── api/                    # API routes
│   ├── auth/               # Authentication
│   ├── admin/              # Admin APIs
│   ├── clients/            # Client APIs
│   ├── sales/              # Sales APIs
│   ├── services/           # Service config APIs
│   ├── acquisition/        # War room APIs
│   └── webhooks/           # Stripe webhooks
│
├── login/                  # Login page
├── unauthorized/           # 403 page
├── book/[slug]/            # Public booking links
├── roi-calculator/         # Public marketing tool
└── website-audit/          # Public marketing tool

2.3 Route Groups Explained

What are (client), (admin)?

They're route groups - they organize files WITHOUT adding to the URL.

File: app/(client)/dashboard/page.tsx
URL: /dashboard (NOT /client/dashboard)

File: app/(admin)/admin/dashboard/page.tsx
URL: /admin/dashboard

Why use them?

1. Different layouts: Client portal has different sidebar than admin
2. Middleware filtering: Apply different auth rules
3. Organization: Group related routes visually

2.4 The lib/ Directory (Shared Code)

lib/
├── db/                     # Database modules
│   ├── index.ts            # Main export
│   ├── client-queries.ts   # Client-related queries
│   ├── admin-queries.ts    # Admin-related queries
│   ├── sales-queries.ts    # Sales-related queries
│   └── acquisition.ts      # War room queries
│
├── scrapers/               # Lead generation
│   ├── yelp.ts
│   ├── google-maps.ts
│   └── website-intel.ts
│
├── auth.ts                 # Auth helpers (validateSession, etc.)
├── encryption.ts           # AES-256-GCM encryption
├── rate-limit.ts           # API rate limiting
├── logger.ts               # Logging utility
├── stripe.ts               # Stripe integration
├── hubspot.ts              # HubSpot CRM
├── analytics.tsx           # Google Analytics
├── validation.ts           # Input validation
└── theme.ts                # Tailwind utilities

2.5 The database/ Directory

database/
├── schema.sql              # Complete schema (source of truth)
├── maediia.db              # Live SQLite database
├── maediia.db-shm          # SQLite shared memory
├── maediia.db-wal          # SQLite write-ahead log
├── acquisition_schema.sql  # War room tables
└── migrations/             # Schema migrations
    ├── 001_initial.sql
    ├── 002_feature_flags.sql
    └── ...

Important: Never edit maediia.db directly. Always use migrations or the API.