Project Structure

Top-Level Layout

platform/
├── src/                    # Application source
│   ├── components/         # UI components
│   │   ├── astro/          # Static Astro components
│   │   └── islands/        # Interactive Preact islands
│   ├── config/             # Portal UI theme configs
│   ├── data/               # Static data (dummy units, agents)
│   ├── db/                 # Database schema and connection
│   │   ├── index.ts        # DB connection (pg or Neon HTTP)
│   │   └── schema.ts       # Drizzle schema definitions
│   ├── layouts/            # Page layouts
│   ├── lib/                # Business logic and utilities
│   │   ├── auth/           # Authentication (Lucia, CRM, OTP)
│   │   ├── audit/          # Audit logging
│   │   ├── cloudflare/     # Cloudflare API wrappers
│   │   ├── db/             # Tenant scoping helpers
│   │   ├── directus/       # Directus API clients
│   │   ├── documents/      # Document download service
│   │   ├── favorites/      # Favorites service
│   │   ├── http/           # HTTP utilities
│   │   ├── otp/            # OTP generation/delivery
│   │   ├── portal/         # Portal theme and settings
│   │   ├── profile/        # Buyer profile service
│   │   ├── r2/             # Cloudflare R2 presigned URLs
│   │   ├── storage/        # Storage abstraction
│   │   └── tenant/         # Hostname resolution
│   ├── middleware.ts        # Request middleware (auth dispatch)
│   ├── pages/              # Route pages
│   │   ├── admin/          # CRM pages
│   │   ├── api/            # API route handlers
│   │   ├── operator/       # Operator panel pages
│   │   ├── profile/        # Buyer profile pages
│   │   ├── units/          # Unit listing/detail pages
│   │   └── ...             # Static pages (imprint, privacy, etc.)
│   ├── styles/             # Global CSS (Tailwind)
│   └── env.d.ts            # TypeScript declarations
├── drizzle/                # Database migrations
├── scripts/                # Deployment and automation scripts
├── tests/                  # Test suites
├── astro.config.mjs         # Astro configuration
├── docker-compose.yml       # Docker Compose (main branch)
├── wrangler.jsonc           # Wrangler config (spike/cf-runtime)
└── wrangler.toml            # Wrangler env config (spike/cf-runtime)

Key Paths on spike/cf-runtime

src/
├── lib/
│   ├── cloudflare/custom-hostnames.ts   # Custom hostname API
│   ├── auth/admin-lucia.ts               # Admin Lucia instance
│   ├── auth/admin-session.ts             # CRM session helpers
│   ├── auth/cf-access.ts                 # CF Access JWT verification
│   ├── audit/index.ts                    # Audit logging
│   ├── r2/{client,presign}.ts            # R2 presigned URLs
│   ├── tenant/resolve-host.ts            # Hostname resolution
│   └── db/scoped.ts                      # Tenant scoping helpers
├── pages/
│   ├── admin/                            # CRM route pages
│   ├── api/admin/                        # CRM API handlers
│   ├── api/operator/                     # Operator API handlers
│   └── operator/                         # Operator panel pages

Naming Conventions

Pattern	Example	Purpose
*.astro	UnitListing.astro	Astro component/page (SSR)
*.tsx	UnitFilterBar.tsx	Preact island component
*.ts	admin-session.ts	Server logic (src/lib/) or API handler (src/pages/api/)
*.test.ts	hash.test.ts	Vitest test file
*.mjs	migrate.mjs	Node.js script (scripts/)
*.sh	deploy-client.sh	Shell script (scripts/)