the-collective-hub/AGENTS.md

Project Configuration

• Language: TypeScript
• Package Manager: npm
• Runtime: Node.js 22
• Framework: SvelteKit 2.8.1 + Svelte 5
• Database: PostgreSQL
• ORM: Drizzle ORM 0.45 (with Kysely 0.29 as query builder)
• Auth: Better Auth 1.6 (Discord OAuth)
• Image processing: sharp 0.34
• Dev tools: prettier, eslint, vitest, playwright, tailwindcss v4
• Deployment: Coolify (multi-deploy), Docker
• CDN: Bunny CDN or S3-compatible
• Add-ons: mcp

---

The Collective Hub — AI Agent Instructions

Single entry point for all AI assistants (Cline, Roo Code, Continue.dev, etc.) working on this project.

---

1. Project Identity

The Collective Hub — A reusable SvelteKit website template system for launching branded landing pages for online theater hosts, watch-party communities, and Discord communities. One codebase → multiple deployed sites → one shared database + CDN.

We help community organizers look professional online, show their events, attract new members, and build a home for their community — without needing to build a website from scratch.

Resource	Link
This file	AGENTS.md
Project brief	docs/00-project-brief.md
Architecture plan	docs/01-architecture-plan.md
Database plan	docs/02-database-plan.md
Feature roadmap	docs/03-feature-roadmap.md
Environment variables	docs/04-environment-variables.md
Admin UX plan	docs/05-admin-ux-plan.md
Public site UX plan	docs/06-public-site-ux-plan.md
Development plan	docs/07-development-plan.md
Open questions	docs/08-open-questions.md
Risks and rules	docs/09-risks-and-rules.md
Multi-tenant architecture	multi-tenant-architecture.instructions.md
Database schema	database-schema.instructions.md
Auth & roles	auth-and-roles.instructions.md
Deployment guide	deployment-guide.instructions.md
Admin panel	admin-panel.instructions.md
CDN & assets	cdn-and-assets.instructions.md
Public site theming	public-site-theming.instructions.md
API route patterns	api-route-patterns.instructions.md
Testing (multi-tenant)	testing-multi-tenant.instructions.md

---

2. Platform Capabilities

Core Platform

• Multi-deployment model: Each Coolify deployment runs the same Docker image; differentiated only by SITE_SLUG env var
• Data scoping: Every table has siteId — multi-tenant from day one
• Site resolution: hooks.server.ts → site-resolver.ts → locals.site for all downstream code
• Auth: Owner bootstrap via OWNER_DISCORD_ID; super admin via SUPER_ADMIN_DISCORD_IDS; roles: owner/admin/editor
• CDN: Database stores only CDN keys (paths); full URLs constructed via CDN_BASE_URL env var
• Image processing: Automatic webp conversion + optimization via sharp on upload

Admin Panel

• Settings: Edit site name, tagline, and general configuration
• Branding: Upload logo, background image, favicon; select color theme
• Homepage editor: Hero title, subtitle, about text, CTA button text/link
• Links manager: Add/edit/delete/reorder nav links and social links
• Events manager: Create, edit, publish/unpublish events with timezone support
• Asset library: Browse, upload, and manage media files with CDN URL copying

Public Site

• SSR-only single landing page: Hero → About → Events → Social Links → Footer
• Theme-aware: CSS custom properties generated from site settings (dark/light/custom presets)
• Responsive: Works on mobile and desktop without client JS
• Accessible: Proper heading hierarchy, alt text, sufficient contrast

Infrastructure

• Coolify multi-deploy: One Git repo, multiple deployments, shared database
• Docker containerized: Multi-stage Dockerfile, deployed via Coolify
• Migration safety: One deployment runs migrations (RUN_MIGRATIONS=true); others skip
• Shared CDN: Single bucket, site-scoped paths (sites/{siteSlug}/...)

---

3. Target Audience

David (System Maintainer)

• Deploys new sites, maintains the shared codebase, pushes updates
• Has super admin access across all sites via SUPER_ADMIN_DISCORD_IDS
• Needs: reliable deployment process, clean migration strategy, maintainable code

Site Owners (Theater Hosts / Community Organizers)

• Log in via Discord, customize their site through the admin panel
• Non-technical but motivated — need a simple, intuitive admin UI
• Needs: change branding, edit content, manage events, upload images

Site Visitors (Community Members & Newcomers)

• Visit the public landing page to learn about the community
• Want to see what the community is about, when events happen, how to join
• Needs: fast-loading page, clear info, easy access to Discord/social links

---

4. Project Structure

.roo/
  skills/                   ← Roo Code skills for scaffolding and automation
    admin-page/
    api-endpoint/
    db-migration/
    generate-api-test/
    generate-component-test/
    new-component/
    new-route/
    run-tests/
    test-coverage/
.github/
  instructions/             ← Development guidelines for The Collective Hub
    multi-tenant-architecture.instructions.md
    database-schema.instructions.md
    auth-and-roles.instructions.md
    deployment-guide.instructions.md
    admin-panel.instructions.md
    cdn-and-assets.instructions.md
    public-site-theming.instructions.md
    api-route-patterns.instructions.md
    testing-multi-tenant.instructions.md
    bits-ui.instructions.md
    components.instructions.md
    icons.instructions.md
    server-ts.instructions.md
    svelte-ts.instructions.md
    svelte5.instructions.md
    tailwindcss.instructions.md
    testing.instructions.md
  prompts/                  ← Scaffolding templates for routes, components, API, DB
    new-route.prompt.md
    generate-component-test.prompt.md
    generate-api-endpoint.prompt.md
    generate-admin-page.prompt.md
    generate-db-migration.prompt.md
    generate-svelte-component.prompt.md
    generate-seed-data.prompt.md
    test-coverage.prompt.md
  workflows/                ← CI/CD and release automation
docs/                         ← Architecture, database, roadmap, environment docs
 00-project-brief.md
 01-architecture-plan.md
 02-database-plan.md
 03-feature-roadmap.md
 04-environment-variables.md
 05-admin-ux-plan.md
 06-public-site-ux-plan.md
 07-development-plan.md
 08-open-questions.md
 09-risks-and-rules.md
drizzle/                      ← Drizzle migration files
scripts/
  seed.mjs                    ← Database seed script for local dev
src/
  app.d.ts                    ← App types, locals augmentation
  app.html                    ← HTML shell
  hooks.server.ts             ← Site resolver + auth + migration runner
  lib/
    server/
      auth.ts                 ← Better Auth configuration
      cdn.ts                  ← CDN URL helpers
      site-resolver.ts        ← Site loading by SITE_SLUG
      db/
        index.ts              ← Drizzle + postgres connection
        schema.ts             ← All table definitions
        seed.ts               ← Optional seed data
        migrate.ts            ← Migration runner
    shared/
      types.ts                ← Shared TypeScript types (SiteSettingsData, SiteContext, etc.)
  routes/
    +layout.server.ts         ← Root layout, loads site for all pages
    +layout.svelte            ← Root layout shell
    +page.server.ts           ← Public homepage data loading
    +page.svelte              ← Public homepage
    login/
      +page.svelte            ← Login page (Discord redirect)
    admin/
      +layout.server.ts       ← Admin auth guard
      +layout.svelte          ← Admin shell/nav
      +page.svelte            ← Admin dashboard
      settings/
        +page.server.ts       ← Site settings editor
        +page.svelte
      branding/
        +page.server.ts       ← Logo, colors, theme
        +page.svelte
      assets/
        +page.server.ts       ← Asset library
        +page.svelte
    api/
      assets/
        +server.ts            ← Upload endpoint
static/                       ← Favicon

The .roo/skills/ directory contains reusable skills for common development tasks — scaffolding admin pages, API endpoints, database migrations, components, routes, and generating tests. These are auto-detected by Roo Code when running in this project.

Tech Stack Instructions

The repo includes development guidelines for the web application's tech stack:

File	Purpose
multi-tenant-architecture.instructions.md	Site resolution, data scoping, deployment model, env vars
database-schema.instructions.md	All tables, relationships, indexes, migration strategy
auth-and-roles.instructions.md	Better Auth, Discord OAuth, role system, super admin
deployment-guide.instructions.md	Coolify multi-deploy, Docker, migration runner, env setup
admin-panel.instructions.md	Admin layout, auth guards, form patterns, admin pages
cdn-and-assets.instructions.md	CDN helpers, image upload, webp conversion, URL construction
public-site-theming.instructions.md	SSR-only landing page, CSS custom properties, theme presets
api-route-patterns.instructions.md	API route conventions, asset upload, event CRUD, validation
testing-multi-tenant.instructions.md	Multi-tenant test patterns, mocking site context, auth testing
bits-ui.instructions.md	Component patterns for bits-ui library
components.instructions.md	Svelte 5 component architecture and conventions
icons.instructions.md	Lucide icon usage guidelines
server-ts.instructions.md	SvelteKit server-side TypeScript patterns, Drizzle queries
svelte-ts.instructions.md	TypeScript conventions for Svelte projects
svelte5.instructions.md	Svelte 5 runes, snippets, and migrations
tailwindcss.instructions.md	Tailwind CSS v4 configuration and patterns
testing.instructions.md	Vitest + Playwright testing patterns

Svelte 5 note: <svelte:component> is deprecated. Use {@const ComponentVar = ...} in the template and render it as <ComponentVar /> instead. See svelte5.instructions.md for details and migration examples.

---

5. How AI Agents Should Operate

This section defines how AI agents (Cline, Roo Code, Copilot, etc.) should work within this development context.

Follow the Architecture

• Always scope queries by siteId. Every database query that touches site-owned data must filter by siteId from locals.site. Missing a siteId filter is the most common multi-tenant bug.
• Respect the phase roadmap. Phase 1 (Foundation) must be complete before Phase 2 starts. Don't build features from Phase 3+ before the core works. See docs/03-feature-roadmap.md.
• Use the correct env pattern. Server-side secret env vars use $env/dynamic/private. Never import private env modules from client-side code.
• Store CDN keys, not URLs. Database fields like cdnKey store paths (e.g., sites/bad-movies-theater/logo.webp), never full URLs. Use the cdnUrl() helper from src/lib/server/cdn.ts to construct full URLs.

Stay On-Architecture

• No site-specific conditionals. Never write if (site.slug === 'bad-movies-theater'). All customization comes from database settings (branding, theme, homepage content).
• Prefer JSON settings over migrations. Adding a setting to the siteSettings.settings JSON column requires no database migration. Only create new tables/tables for structured data that needs indexes, foreign keys, or complex queries.
• One layout in V1. Don't create multiple layout options. One clean, flexible layout that adapts to content is better than three half-baked options.
• Additive migrations only. In production, always use additive changes (new columns, new tables). Avoid renames or destructive operations.

Development Principles

• Code for the shared codebase. Every feature should work for all sites. If a feature is only useful for one site, reconsider whether it belongs in the shared codebase.
• Keep the admin panel simple. The admin exists to serve the public page. Don't build complex admin UIs before the public rendering works.
• Security is everyone's responsibility. Sanitize file uploads, validate all form input server-side, never expose private env vars to the client, protect against XSS in rendered content.
• Test the boundary conditions. Test with no data (empty site), test with missing settings, test with inactive sites, test with various role levels.

When Creating Templates

• Use clear [placeholders] for variables that the developer must customize
• Include a brief example filled out so they see the expected pattern
• Reference the relevant instruction file for detailed conventions

---

6. Hard Rules (Non-Negotiable)

1. Always filter by siteId. Every Drizzle query on site-owned data must include a siteId filter. Missing this is the most common multi-tenant bug and causes data leaks between sites.

2. Store CDN keys, not full URLs. Database fields store paths like sites/{slug}/logo.webp. The cdnUrl() helper constructs full URLs using CDN_BASE_URL. Never store a full URL in the database.

3. One deployment runs migrations. Only the deployment with RUN_MIGRATIONS=true runs database migrations. Deploy this one first when schema changes are included in a release.

4. No site-specific conditional logic. Never write if (site.slug === 'some-site'). All per-site differences come from database settings. If a site genuinely needs a unique feature, build it as a configurable option for all sites.

5. Never commit .env files. Environment variables are configured per-deployment in Coolify. The .env file is in .gitignore and must never be committed.

6. Use $lib aliases, not relative paths. Always import from $lib/server/db, $lib/components/, etc. Never use relative imports like ../../lib/server/db.

7. Co-locate tests. Test files go next to the source they test. Server tests use .test.ts, browser component tests use .svelte.test.ts.

8. No svelte-ignore suppression comments. All accessibility and type issues must be fixed properly. Never hide a warning behind a suppression comment.

9. Prefer additive migrations. In production, add new columns and tables. Avoid destructive operations (ALTER DROP, RENAME). JSON settings columns reduce migration frequency.

10. Respect the phase roadmap. Phase 1 must be fully working (public site + admin login + settings save) before Phase 2. A working simple site is more valuable than a half-built complex one.

---

7. File Reference Index

File	Purpose
AGENTS.md	This file — master instructions for all AI agents working on The Collective Hub project
.github/copilot-instructions.md	Copilot-specific instructions for development tasks
docs/00-project-brief.md	Project overview — what The Collective Hub is and who it's for
docs/01-architecture-plan.md	Technical architecture — stack, site resolution, deployment model
docs/02-database-plan.md	Database schema — all tables, relationships, migration strategy
docs/03-feature-roadmap.md	Development phases and feature priorities across the roadmap
docs/04-environment-variables.md	Environment variable reference — shared vs per-site
docs/05-admin-ux-plan.md	Admin panel user experience design and layout
docs/06-public-site-ux-plan.md	Public site user experience and page structure
docs/07-development-plan.md	Step-by-step development plan and implementation order
docs/08-open-questions.md	Open design questions and pending decisions
docs/09-risks-and-rules.md	Critical risks and design pitfalls to avoid
.github/instructions/multi-tenant-architecture.instructions.md	Site resolution flow, data scoping, deployment model
.github/instructions/database-schema.instructions.md	All tables, relationships, Drizzle query patterns
.github/instructions/auth-and-roles.instructions.md	Better Auth, Discord OAuth, roles, auth guards
.github/instructions/deployment-guide.instructions.md	Coolify multi-deploy, Docker, migration runner
.github/instructions/admin-panel.instructions.md	Admin routes, auth guards, form actions
.github/instructions/cdn-and-assets.instructions.md	CDN helpers, upload flow, sharp processing
.github/instructions/public-site-theming.instructions.md	SSR page, CSS custom properties, theme system
.github/instructions/api-route-patterns.instructions.md	API route conventions, validation, site scoping
.github/instructions/testing-multi-tenant.instructions.md	Multi-tenant test patterns, mocking, auth testing
.github/instructions/bits-ui.instructions.md	Bits UI headless component patterns
.github/instructions/components.instructions.md	Svelte 5 component architecture
.github/instructions/icons.instructions.md	Lucide icon usage guidelines
.github/instructions/server-ts.instructions.md	SvelteKit server-side TypeScript patterns
.github/instructions/svelte-ts.instructions.md	Svelte 5 .svelte.ts reactive module patterns
.github/instructions/svelte5.instructions.md	Svelte 5 runes, snippets, migrations
.github/instructions/tailwindcss.instructions.md	Tailwind CSS v4 configuration
.github/instructions/testing.instructions.md	Vitest + Playwright base testing patterns
.github/prompts/new-route.prompt.md	Scaffold new SvelteKit routes with auth + site-scoped queries
.github/prompts/generate-component-test.prompt.md	Generate Vitest browser component tests
.github/prompts/test-coverage.prompt.md	Analyse coverage gaps and generate missing tests
.github/prompts/generate-admin-page.prompt.md	Scaffold admin page with auth guard + form
.github/prompts/generate-db-migration.prompt.md	Scaffold Drizzle migration for schema changes
.github/prompts/generate-api-endpoint.prompt.md	Scaffold API route with auth + site scoping
.github/prompts/generate-svelte-component.prompt.md	Scaffold Svelte 5 component with runes + Tailwind
.github/prompts/generate-seed-data.prompt.md	Scaffold seed script for local dev
.github/workflows/	CI/CD and release automation
src/lib/server/site-resolver.ts	Site loading by SITE_SLUG — core multi-tenant logic
src/lib/server/auth.ts	Better Auth with Discord OAuth configuration
src/lib/server/cdn.ts	CDN URL construction helpers
src/lib/server/db/schema.ts	All Drizzle table definitions
src/lib/server/db/index.ts	Drizzle + postgres connection
src/lib/shared/types.ts	SiteSettingsData, SiteContext, shared types
scripts/seed.mjs	Database seed script for local dev
Dockerfile	Multi-stage Docker build
docker-compose.yml	Local development with Postgres

---

8. Mode Responsibilities

This section maps AI agent operating modes to development tasks within The Collective Hub context.

Mode	How It's Used Here
🪃 Orchestrator	Breaks down multi-tenant features into discrete tasks; coordinates site resolution, auth integration, admin panel work, and CDN setup; delegates research, implementation, and review stages across phases
🏗️ Architect	Plans technical architecture for multi-tenant features: site resolution flow, database schema additions, admin panel structure, deployment strategy, CDN integration patterns; creates technical specifications for new features
💻 Code	Builds and maintains the SvelteKit platform; implements Drizzle queries, admin form actions, public site rendering, auth guards, CDN upload flows; writes Vitest tests with multi-tenant mocking patterns
❓ Ask	Answers development questions about the codebase; explains multi-tenant architecture patterns (e.g., "how does site resolution work?"); provides recommendations on Drizzle queries, SvelteKit patterns, Postgres optimization
🪲 Debug	Troubleshoots multi-tenant issues (data leaks between sites, wrong site context, auth failures); diagnoses deployment problems (migration conflicts, env var misconfiguration, CDN URL issues); investigates database query performance

---

For new AI agents: Start by reading the relevant instruction file linked in Section 7 above based on your task. When in doubt about architecture or patterns, review the multi-tenant architecture guidelines in multi-tenant-architecture.instructions.md and the risks document in docs/09-risks-and-rules.md. The core philosophy of this project is simple: one codebase, multiple sites, no data leaks, maintainable by one person.