From 293415f349ef90b46991f3c5a48aa866778820b9 Mon Sep 17 00:00:00 2001 From: dallensmith Date: Fri, 5 Jun 2026 22:49:03 -0400 Subject: [PATCH] Initial commit: The Collective Hub planning documentation --- $null | 1 + .gitignore | 36 ++ .../1_mode_creation_workflow.xml | 491 ++++++++++++++++++ .../2_xml_structuring_best_practices.xml | 240 +++++++++ .../3_mode_configuration_patterns.xml | 307 +++++++++++ .../4_instruction_file_templates.xml | 293 +++++++++++ .../5_complete_mode_examples.xml | 91 ++++ .../6_mode_testing_validation.xml | 186 +++++++ .../7_validation_cohesion_checking.xml | 194 +++++++ .roo/rules-mode-writer/8_global_modes.xml | 51 ++ .roo/rules-skill-writer/1_workflow.xml | 116 +++++ .roo/rules-skill-writer/2_best_practices.xml | 94 ++++ .roo/rules-skill-writer/3_common_patterns.xml | 100 ++++ .../4_decision_guidance.xml | 78 +++ .roo/rules-skill-writer/5_examples.xml | 77 +++ .roo/rules-skill-writer/6_error_handling.xml | 17 + .roo/rules-skill-writer/7_communication.xml | 15 + .roo/rules-skill-writer/8_tool_usage.xml | 30 ++ .roomodes | 166 ++++++ docs/00-project-brief.md | 61 +++ docs/01-architecture-plan.md | 273 ++++++++++ docs/02-database-plan.md | 313 +++++++++++ docs/03-feature-roadmap.md | 163 ++++++ docs/04-environment-variables.md | 192 +++++++ docs/05-admin-ux-plan.md | 265 ++++++++++ docs/06-public-site-ux-plan.md | 202 +++++++ docs/07-development-plan.md | 260 ++++++++++ docs/08-open-questions.md | 87 ++++ docs/09-risks-and-rules.md | 152 ++++++ 29 files changed, 4551 insertions(+) create mode 100644 $null create mode 100644 .gitignore create mode 100644 .roo/rules-mode-writer/1_mode_creation_workflow.xml create mode 100644 .roo/rules-mode-writer/2_xml_structuring_best_practices.xml create mode 100644 .roo/rules-mode-writer/3_mode_configuration_patterns.xml create mode 100644 .roo/rules-mode-writer/4_instruction_file_templates.xml create mode 100644 .roo/rules-mode-writer/5_complete_mode_examples.xml create mode 100644 .roo/rules-mode-writer/6_mode_testing_validation.xml create mode 100644 .roo/rules-mode-writer/7_validation_cohesion_checking.xml create mode 100644 .roo/rules-mode-writer/8_global_modes.xml create mode 100644 .roo/rules-skill-writer/1_workflow.xml create mode 100644 .roo/rules-skill-writer/2_best_practices.xml create mode 100644 .roo/rules-skill-writer/3_common_patterns.xml create mode 100644 .roo/rules-skill-writer/4_decision_guidance.xml create mode 100644 .roo/rules-skill-writer/5_examples.xml create mode 100644 .roo/rules-skill-writer/6_error_handling.xml create mode 100644 .roo/rules-skill-writer/7_communication.xml create mode 100644 .roo/rules-skill-writer/8_tool_usage.xml create mode 100644 .roomodes create mode 100644 docs/00-project-brief.md create mode 100644 docs/01-architecture-plan.md create mode 100644 docs/02-database-plan.md create mode 100644 docs/03-feature-roadmap.md create mode 100644 docs/04-environment-variables.md create mode 100644 docs/05-admin-ux-plan.md create mode 100644 docs/06-public-site-ux-plan.md create mode 100644 docs/07-development-plan.md create mode 100644 docs/08-open-questions.md create mode 100644 docs/09-risks-and-rules.md diff --git a/$null b/$null new file mode 100644 index 0000000..5a904c3 --- /dev/null +++ b/$null @@ -0,0 +1 @@ +fatal: not a git repository (or any of the parent directories): .git diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c73ee5b --- /dev/null +++ b/.gitignore @@ -0,0 +1,36 @@ +# Dependencies +node_modules/ +.pnpm-store/ + +# Build output +/build/ +/.svelte-kit/ + +# Environment +.env +.env.* +!.env.example + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# OS +.DS_Store +Thumbs.db + +# Logs +*.log +npm-debug.log* + +# Database +*.db +*.sqlite + +# Docker +.docker/ + +# Misc +*.local diff --git a/.roo/rules-mode-writer/1_mode_creation_workflow.xml b/.roo/rules-mode-writer/1_mode_creation_workflow.xml new file mode 100644 index 0000000..cbdb467 --- /dev/null +++ b/.roo/rules-mode-writer/1_mode_creation_workflow.xml @@ -0,0 +1,491 @@ + + + This workflow guides you through creating new custom modes or editing existing ones + for the Roo Code Software, ensuring comprehensive understanding and cohesive implementation. + + + + + .roomodes in the workspace root directory + + Workspace modes are the default target for project-specific modes and for overrides. + + + + + VS Code globalStorage custom modes settings file (location is environment-specific; open it via the product UI) + + Global modes are used system-wide and are created automatically on Roo Code startup. + + + + + + If the same slug exists in both global modes and workspace modes, the workspace (.roomodes) entry wins. + + + + + + Both files use the same YAML schema: a top-level customModes: list of mode objects. + + + + Mode definitions are YAML objects within customModes:. Use YAML block scalars (e.g., >-) for multi-line text fields when helpful. + + + If you must embed explicit newlines in a quoted string, use \n for newlines and \n\n for blank lines. + + + groups is required and is a YAML array. It may be empty when a mode should not have access to optional permissions. + + + Each groups entry may be: + - a simple string (unrestricted permission group), or + - a structured entry that restricts the permission to a subset of files (e.g., fileRegex + description for edit restrictions). + + + + slug + name + roleDefinition + groups + + + description + whenToUse + + + customInstructions + + + Canonical YAML skeleton (illustrative; keep instructions/tooling details in .roo/rules-[slug]/) + +customModes: + - slug: example-mode + name: Example Mode + description: Short five-word summary + roleDefinition: >- + You are Roo Code, a [specialist type] who... + + Key areas: + - Area one + - Area two + whenToUse: >- + Use this mode when... + groups: + - read + - - edit + - fileRegex: \\.(md|mdx)$ + description: Documentation files only + customInstructions: >- + Optional brief glue text. + + + + + + + + Determine User Intent + + Identify whether the user wants to create a new mode or edit an existing one + + + + + User mentions a specific mode by name or slug + User references a mode directory path (e.g., .roo/rules-[mode-slug]) + User asks to modify, update, enhance, or fix an existing mode + User says "edit this mode" or "change this mode" + + + + + User asks to create a new mode + User describes a new responsibility not covered by existing modes + User says "make a mode for" or "create a mode that" + + + + + + I want to make sure I understand correctly. Are you looking to create a brand new mode or modify an existing one? + + Create a new mode for a specific purpose + Edit an existing mode to add new responsibilities + Fix issues in an existing mode + Enhance an existing mode with better workflows + + + + + + + Resolve Mode Source (Workspace vs Global) + + When the user asks about a specific mode by name/slug (including phrases like "global mode"), resolve where that mode is defined + before doing broad repository searches. + + + + Check the workspace override first by reading .roomodes. + + + If not present (or the user explicitly requests global scope), inspect the global custom modes settings file. + Note: its exact path is determined by the extension at runtime (do not hardcode a machine-specific path). + + + If the mode is workspace-scoped, read its instruction directory .roo/rules-[mode-slug]/. + + + + If the mode entry is found in either .roomodes or the global file, proceed directly to analysis/edits without additional discovery. + + + + + + + + Gather Requirements for New Mode + + Understand what the user wants the new mode to accomplish + + + Ask about the mode's primary purpose and use cases + Identify what types of tasks the mode should handle + Determine what repository access and permissions the mode needs + Clarify any special behaviors or restrictions + + + + What is the primary purpose of this new mode? What types of tasks should it handle? + + A mode for writing and maintaining documentation + A mode for database schema design and migrations + A mode for API endpoint development and testing + A mode for performance optimization and profiling + + + + + + + Design Mode Configuration + + Create the mode definition with all required fields + + + + Default to workspace-scoped modes unless the user explicitly requests a global mode. + + User asks for a mode to be available across all workspaces, or explicitly mentions the global modes file. + + + User asks for a mode for this repo/project only, or wants to commit/share the mode with the repository. + + + + + Unique identifier (lowercase, hyphens allowed) + Keep it short and descriptive (e.g., "api-dev", "docs-writer") + + + Display name with optional emoji + Use an emoji that represents the mode's purpose + + + Detailed description of the mode's role and expertise + + Start with "You are Roo Code, a [specialist type]..." + List specific areas of expertise + Mention key technologies or methodologies + + + + Permission groups the mode can access + + The concrete group names and any nesting structure are runtime-defined and may evolve. + Treat these as conceptual categories and map them to the closest available equivalents. + + + + + + + + + + + + + Short human-readable summary (aim ~5 words) + Keep it scannable and concrete + + + Clear description for the Orchestrator + Explain specific scenarios and task types + + + + Prefer keeping substantial mode guidance in XML files within .roo/rules-[mode-slug]/. + The underlying mode system supports customInstructions, but large instruction blocks there are easier to duplicate/drift. + Use customInstructions only for brief "glue" text when needed. + + Note: the underlying mode system supports a customInstructions field, + but this repository intentionally keeps detailed instructions in + .roo/rules-[mode-slug]/ XML files to avoid duplication and drift. + + + + + Implement File Restrictions + + Configure appropriate file access permissions + + + Restrict edit access to specific file types + +groups: + - read + - - edit + - fileRegex: \.(md|txt|rst)$ + description: Documentation files only + - command + + + + Use regex patterns to limit file editing scope + Provide clear descriptions for restrictions + Consider the principle of least privilege + + + + + Create XML Instruction Files + + Design structured instruction files in .roo/rules-[mode-slug]/ + + + Main workflow and step-by-step processes + Guidelines and conventions + Reusable code patterns and examples + Decision criteria and guardrails + Complete workflow examples + + + Use semantic tag names that describe content + Nest tags hierarchically for better organization + Include code examples in CDATA sections when needed + Add comments to explain complex sections + + + + + + + Immerse in Existing Mode + + Fully understand the existing mode before making any changes + + + Locate and read the mode configuration in .roomodes + When global scope is relevant, locate and read the global custom modes settings file and compare slugs for precedence + Read all XML instruction files in .roo/rules-[mode-slug]/ + Analyze the mode's current scope, permissions, and limitations + Understand the mode's role in the broader ecosystem + + + + What specific aspects of the mode would you like to change or enhance? + + Adjust permissions or restrictions + Fix issues with current workflows or instructions + Improve the mode's roleDefinition or whenToUse description + Enhance XML instructions for better clarity + + + + + + + Analyze Change Impact + + Understand how proposed changes will affect the mode + + + Compatibility with existing workflows + Impact on file permissions and capability access + Consistency with mode's core purpose + Integration with other modes + + + Role and scope: roleDefinition matches actual scope and permissions; remove scope creep + Orchestrator routing: whenToUse/whenNotToUse are explicit and distinct from other modes + Permissions: groups and fileRegex follow least-privilege and match instructions + Instructions hygiene: no contradictions or duplicates across XML files + Naming consistency: tag names and terminology are consistent + Deprecated content: remove legacy fields (e.g., customInstructions in .roomodes) + Boundaries: clear handoffs to other modes; no overlapping responsibilities + + + Search for repeated guidance and conflicting directives across files + + + + I've analyzed the existing mode. Here's what I understand about your requested changes. Is this correct? + + Yes, that's exactly what I want to change + Mostly correct, but let me clarify some details + No, I meant something different + I'd like to add additional changes + + + + + + + Plan Modifications + + Create a detailed plan for modifying the mode + + + Identify which files need to be modified + Determine if new XML instruction files are needed + Check for potential conflicts or contradictions + Plan the order of changes for minimal disruption + + + + Consolidate overlapping instructions into a single source of truth + Align with XML best practices (semantic tags, hierarchical nesting) + Standardize whenToUse/whenNotToUse language and boundaries + Centralize preamble rules and autonomy calibration + + + Tighten fileRegex to least-privilege; add clear descriptions + Ensure instructions match configured permissions + + + Split overly long files; ensure 6_error_handling and 7_communication are present or updated + + + Update 5_examples.xml to reflect new workflows and refactors + Include before/after diffs where helpful + + + + .roomodes: roleDefinition and whenToUse + .roo/rules-[slug]/ XML instruction files + Examples and quick_reference sections + + + + + Silent Self-Reflection Rubric + Privately evaluate the planned changes against a 5–7 category rubric before implementation + + Cohesion across files + Permissions and file restrictions (least privilege) + Orchestrator fit (whenToUse/whenNotToUse clarity) + XML structure and naming consistency + Mode boundaries and handoff points + Examples and testability + + Iterate on the plan until it passes the rubric; do not expose the rubric to the user + + + + Implement Changes + + Apply the planned modifications to the mode + + + Update .roomodes configuration if needed + Modify existing XML instruction files + Create new XML instruction files if required + Update examples and documentation + + + Remove duplicate or contradictory instruction blocks across XML files + Delete or migrate deprecated fields (e.g., customInstructions in .roomodes) + Tighten fileRegex patterns and add clear descriptions + Normalize tag names, terminology, and structure + Ensure whenToUse/whenNotToUse and handoff rules are explicit + + + Validate file restriction patterns against the intended file sets + Confirm permissions match instruction expectations + Re-run validation (section 5) and testing (section 6) + Scan the repository for legacy references and remove/modernize as needed + + + + + + + + Validate Cohesion and Consistency + + Ensure all changes are cohesive and don't contradict each other + + + + Mode slug follows naming conventions + File restrictions align with mode purpose (least privilege) + Permissions are appropriate + whenToUse clearly differentiates from other modes + + + All XML files follow consistent structure + No contradicting instructions between files; contradiction hierarchy and resolutions documented + Examples align with stated workflows + Instructions match granted permissions and file restrictions + + + Mode integrates well with Orchestrator + Clear boundaries with other modes + Handoff points are well-defined + + + + + I've completed the validation checks. Would you like me to review any specific aspect in more detail? + + Review the file permission patterns + Check for workflow contradictions + Verify integration with other modes + Everything looks good, proceed to testing + + + + + + + Test and Refine + + Verify the mode works as intended + + + Mode appears in the mode list + File restrictions work correctly + Instructions are clear and actionable + Mode integrates well with Orchestrator + All examples are accurate and helpful + Changes don't break existing functionality (for edits) + New behavior works as expected + + + + + + Create mode in .roomodes for project-specific modes + Create mode in the global custom modes settings file for system-wide modes (path is environment-specific) + Verify the .roo folder structure contains expected rule directories and XML files + Validate file regex patterns against the intended file sets (avoid overbroad matches) + Find existing mode implementations and patterns to reuse + Read all XML files in a mode directory to understand its structure + Always validate changes for cohesion and consistency + + diff --git a/.roo/rules-mode-writer/2_xml_structuring_best_practices.xml b/.roo/rules-mode-writer/2_xml_structuring_best_practices.xml new file mode 100644 index 0000000..8ba9dbe --- /dev/null +++ b/.roo/rules-mode-writer/2_xml_structuring_best_practices.xml @@ -0,0 +1,240 @@ + + + XML tags help LLMs parse prompts more accurately, leading to higher-quality outputs. + This guide covers best practices for structuring mode instructions using XML. + + + + + Clearly separate different parts of your instructions and ensure well-structured content + + + Reduce errors caused by the model misinterpreting parts of your instructions + + + Easily find, add, remove, or modify parts of instructions without rewriting everything + + + Having the model use XML tags in its output makes it easier to extract specific parts of responses + + + + + + Use the same tag names throughout your instructions + + Always use for workflow steps, not sometimes or + + + + + Tag names should clearly describe their content + + detailed_steps + error_handling + validation_rules + + + stuff + misc + data1 + + + + + Nest tags to show relationships and structure + + + + Gather requirements + Validate inputs + + + Process data + Generate output + + + + + + + + + For step-by-step processes + + + + + For providing code examples and demonstrations + + + + + For rules and best practices + + + + + For documenting decision criteria and guardrails + + + + + + + Use consistent indentation (2 or 4 spaces) for nested elements + + + Add line breaks between major sections for readability + + + Use XML comments to explain complex sections + + + Use CDATA for code blocks or content with special characters: + your code here + + + Use attributes for metadata, elements for content: + + + The actual step content + + + + + Keep narrative outputs concise; reserve detailed exposition for code, diffs, and structured outputs. Prefer readable, maintainable code with clear names; avoid one-liners unless explicitly requested. + + + + + + Avoid completely flat structures without hierarchy + + + +Do this + +Then this + +Finally this + + + + + + + Do this + Then this + Finally this + + + + + + + Don't mix naming conventions + + Mixing camelCase, snake_case, and kebab-case in tag names + + + Pick one convention (preferably snake_case for XML) and stick to it + + + + + Avoid tags that don't convey meaning + data, info, stuff, thing, item + user_input, validation_result, error_message, configuration + + + Avoid asking the user to confirm obvious next steps on straightforward tasks + Asking multiple clarifying questions before acting when the task is simple + Proceed when next steps are clear; ask only when critical ambiguity remains; document assumptions + + + + Avoid repetitive or redundant searches when the relevant target is already identified + Running multiple identical searches instead of acting + Stop once the change is clearly identified; then implement + + + + Avoid duplicating runtime behavior that is already defined elsewhere + Documenting execution constraints, operation ordering, or invocation details + Focus on intent, artifacts, decision criteria, and validation expectations + + + + + + Reference XML content in instructions: + "Using the workflow defined in <workflow> tags..." + + + Combine XML structure with other techniques like multishot prompting + + + Use XML tags in expected outputs to make parsing easier + + + Create reusable XML templates for common patterns + + + diff --git a/.roo/rules-mode-writer/3_mode_configuration_patterns.xml b/.roo/rules-mode-writer/3_mode_configuration_patterns.xml new file mode 100644 index 0000000..16c1f5f --- /dev/null +++ b/.roo/rules-mode-writer/3_mode_configuration_patterns.xml @@ -0,0 +1,307 @@ + + + Common patterns and templates for creating different types of modes, with examples from existing modes in the Roo-Code software. + + + + + + Modes focused on specific technical domains or tasks + + + Deep expertise in a particular area + Restricted file access based on domain + Specialized workflows and decision criteria + + +- slug: api-specialist + name: πŸ”Œ API Specialist + roleDefinition: >- + You are Roo Code, an API development specialist with expertise in: + - RESTful API design and implementation + - GraphQL schema design + - API documentation with OpenAPI/Swagger + - Authentication and authorization patterns + - Rate limiting and caching strategies + - API versioning and deprecation + + You ensure APIs are: + - Well-documented and discoverable + - Following REST principles or GraphQL best practices + - Secure and performant + - Properly versioned and maintainable + whenToUse: >- + Use this mode when designing, implementing, or refactoring APIs. + This includes creating new endpoints, updating API documentation, + implementing authentication, or optimizing API performance. + groups: + - read + - - edit + - fileRegex: (api/.*\.(ts|js)|.*\.openapi\.yaml|.*\.graphql|docs/api/.*)$ + description: API implementation files, OpenAPI specs, and API documentation + - command + - mcp + + + + + + Modes that guide users through multi-step processes + + + Step-by-step workflow guidance + Heavy use of focused clarifying questions + Process validation at each step + + +- slug: migration-guide + name: πŸ”„ Migration Guide + roleDefinition: >- + You are Roo Code, a migration specialist who guides users through + complex migration processes: + - Database schema migrations + - Framework version upgrades + - API version migrations + - Dependency updates + - Breaking change resolutions + + You provide: + - Step-by-step migration plans + - Automated migration scripts + - Rollback strategies + - Testing approaches for migrations + whenToUse: >- + Use this mode when performing any kind of migration or upgrade. + This mode will analyze the current state, plan the migration, + and guide you through each step with validation. + groups: + - read + - edit + - command + + + + + + Modes focused on code analysis and reporting + + + Read-heavy operations + Limited or no edit permissions + Comprehensive reporting outputs + + +- slug: security-auditor + name: πŸ”’ Security Auditor + roleDefinition: >- + You are Roo Code, a security analysis specialist focused on: + - Identifying security vulnerabilities + - Analyzing authentication and authorization + - Reviewing data validation and sanitization + - Checking for common security anti-patterns + - Evaluating dependency vulnerabilities + - Assessing API security + + You provide detailed security reports with: + - Vulnerability severity ratings + - Specific remediation steps + - Security best practice recommendations + whenToUse: >- + Use this mode to perform security audits on codebases. + This mode will analyze code for vulnerabilities, check + dependencies, and provide actionable security recommendations. + groups: + - read + - command + - - edit + - fileRegex: (SECURITY\.md|\.github/security/.*|docs/security/.*)$ + description: Security documentation files only + + + + + + Modes for generating new content or features + + + Broad file creation permissions + Template and boilerplate generation + Interactive design process + + +- slug: component-designer + name: 🎨 Component Designer + roleDefinition: >- + You are Roo Code, a UI component design specialist who creates: + - Reusable React/Vue/Angular components + - Component documentation and examples + - Storybook stories + - Unit tests for components + - Accessibility-compliant interfaces + + You follow design system principles and ensure components are: + - Highly reusable and composable + - Well-documented with examples + - Fully tested + - Accessible (WCAG compliant) + - Performance optimized + whenToUse: >- + Use this mode when creating new UI components or refactoring + existing ones. This mode helps design component APIs, implement + the components, and create comprehensive documentation. + groups: + - read + - - edit + - fileRegex: (components/.*|stories/.*|__tests__/.*\.test\.(tsx?|jsx?))$ + description: Component files, stories, and component tests + - browser + - command + + + + + + Configuration patterns to keep modes focused, cohesive, and clearly scoped + + Prefer a single source of truth for each rule; avoid duplicated instructions + Prefer least privilege; keep file restrictions aligned with purpose + Define acceptance criteria and validation gates for typical tasks + Define explicit boundaries and handoff points to other modes + Keep narrative brief; reserve detail for structured outputs and diffs + + + + Tight scope, least privilege, clear boundaries; prefer small targeted changes + + + Step-by-step process with validation gates; ask clarifying questions only when necessary + + + Read-heavy; edits typically constrained to reporting or documentation outputs + + + Broader creation scope; ensure examples and tests are included when applicable + + + + + + + For modes that only work with documentation + +groups: + - read + - - edit + - fileRegex: \.(md|mdx|rst|txt)$ + description: Documentation files only + + + + + For modes that work with test files + +groups: + - read + - command + - - edit + - fileRegex: (__tests__/.*|__mocks__/.*|.*\.test\.(ts|tsx|js|jsx)$|.*\.spec\.(ts|tsx|js|jsx)$) + description: Test files and mocks + + + + + For modes that manage configuration + +groups: + - read + - - edit + - fileRegex: (.*\.config\.(js|ts|json)|.*rc\.json|.*\.yaml|.*\.yml|\.env\.example)$ + description: Configuration files (not .env) + + + + + For modes that need broad access + +groups: + - read + - edit # No restrictions + - command + - browser + - mcp + + + + + + + Use lowercase with hyphens + api-dev, test-writer, docs-manager + apiDev, test_writer, DocsManager + + + + Use title case with descriptive emoji + πŸ”§ API Developer, πŸ“ Documentation Writer + api developer, DOCUMENTATION WRITER + + + + + πŸ§ͺ + πŸ“ + 🎨 + πŸͺ² + πŸ—οΈ + πŸ”’ + πŸ”Œ + πŸ—„οΈ + ⚑ + βš™οΈ + + + + + + + Ensure whenToUse/whenNotToUse are clear for Orchestrator mode + + Specify concrete task types the mode handles + Include trigger keywords or phrases + Differentiate from similar modes + Mention specific file types or areas + Define whenNotToUse with negative triggers and explicit handoffs + State stop/ask/handoff rules + State default verbosity policy (low narrative; verbose diffs) + + + + + Define explicit stop conditions, confirmation thresholds, and handoff/ask triggers + + Done-ness: acceptance criteria and validation gates are defined + Handoff rules to other modes or β€œask a clarifying question” conditions are explicit + Boundaries, risks, and validation gates are documented + + + + + Set verbosity defaults to keep narrative short and code edits clear + + Low narrative verbosity in status/progress text + High detail only inside code/diffs and structured outputs + Code clarity over cleverness; avoid code-golf and cryptic names + + + + + Define clear boundaries between modes + + Avoid overlapping responsibilities + Make handoff points explicit + Switch modes when appropriate (mechanism varies) + Document mode interactions + + + + diff --git a/.roo/rules-mode-writer/4_instruction_file_templates.xml b/.roo/rules-mode-writer/4_instruction_file_templates.xml new file mode 100644 index 0000000..fcc2bba --- /dev/null +++ b/.roo/rules-mode-writer/4_instruction_file_templates.xml @@ -0,0 +1,293 @@ + + + Templates and examples for creating XML instruction files that provide + detailed guidance for each mode's behavior and workflows. + + Requirements: + - Do not reference runtime implementation details (function names, command names, UI entry points, or execution syntax). + - Do not duplicate operational policies that are already defined by the runtime/system prompt. + - Focus on workflow intent, required artifacts, decision criteria, and validation expectations. + + + + Number files to indicate execution order + Use descriptive names that indicate content + Keep related instructions together + + 1_workflow.xml - Main workflow and processes + 2_best_practices.xml - Guidelines and conventions + 3_common_patterns.xml - Reusable code patterns + 4_decision_guidance.xml - Decision criteria and guardrails + 5_examples.xml - Complete workflow examples + 6_error_handling.xml - Error scenarios and recovery + 7_communication.xml - User interaction guidelines + + + + + Template for main workflow files (1_workflow.xml) + + + + + Template for best practices files (2_best_practices.xml) + + + + + Template for decision criteria and guardrails (4_decision_guidance.xml) + + + + + Template for example files (5_examples.xml) + + + + + Template for communication guidelines (7_communication.xml) + + + diff --git a/.roo/rules-mode-writer/5_complete_mode_examples.xml b/.roo/rules-mode-writer/5_complete_mode_examples.xml new file mode 100644 index 0000000..31e5485 --- /dev/null +++ b/.roo/rules-mode-writer/5_complete_mode_examples.xml @@ -0,0 +1,91 @@ + + + Canonical examples for creating and editing Roo Code modes. Each example demonstrates structured workflows, least-privilege configuration, contradiction resolution, and completion formatting, without referencing runtime implementation details. + + + + + Edit the Test mode to add benchmark testing and performance guidance using Vitest's bench API. + + + I want to edit the test mode to add benchmark testing support. + + + + Clarify scope and features + + Ask the user a focused clarifying question to confirm which scope/features to include; provide 2–4 actionable options. Outcome: selected scope. + + User selects: Add benchmark testing with Vitest bench API + + + + Immerse in current mode config and instructions + + Review .roomodes, inventory .roo/rules-test recursively, and review .roo/rules-test/1_workflow.xml. Outcome: confirm roleDefinition, file restrictions, and existing workflows. + + Confirm roleDefinition, file restrictions, and existing workflows. + + + + Update roleDefinition in .roomodes + + Edit .roomodes to update the roleDefinition, adding benchmark testing and performance guidance topics. Outcome: roleDefinition updated to include performance/bench themes. + + + + + Extend file restrictions to include .bench files + + Edit .roomodes to extend the fileRegex to include .bench.(ts|tsx|js|jsx) and update the description accordingly. Outcome: file restrictions now cover benchmark files. + + + + + Create benchmark guidance file + + Create a new file at .roo/rules-test/5_benchmark_testing.xml with guidance and examples. Outcome: new guidance file available to the mode. + + + + Guidelines for performance benchmarks using Vitest bench API + + + Basic structure + +import { bench, describe } from 'vitest'; + + +describe('Array operations', () => { + bench('Array.push', () => { + const arr: number[] = []; + for (let i = 0; i < 1000; i++) arr.push(i); + }); + + bench('Array spread', () => { + let arr: number[] = []; + for (let i = 0; i < 1000; i++) arr = [...arr, i]; + }); +}); + + + + + Use meaningful names and isolate benchmarks + Document expectations and thresholds + + + + + + + + Provide a concise summary of what was accomplished and how it addresses the user's request. + + + + Important lesson from this example + Pattern that can be reused + + + diff --git a/.roo/rules-mode-writer/6_mode_testing_validation.xml b/.roo/rules-mode-writer/6_mode_testing_validation.xml new file mode 100644 index 0000000..8274fb7 --- /dev/null +++ b/.roo/rules-mode-writer/6_mode_testing_validation.xml @@ -0,0 +1,186 @@ + + + Guidelines for testing and validating newly created modes to ensure they function correctly and integrate well with the Roo Code ecosystem. + + + + + + Mode slug is unique and follows naming conventions + No spaces, lowercase, hyphens only + + + All required fields are present and non-empty + slug, name, roleDefinition, groups + + + Avoid large customInstructions blocks in .roomodes + + Prefer storing substantial mode guidance in XML files under .roo/rules-[slug]/. + Small, high-level glue text in customInstructions is acceptable when needed. + + + + File restrictions use valid regex patterns + Validate by comparing the regex pattern against the intended file sets; confirm patterns match intended files and avoid overbroad matches. + + + whenToUse clearly differentiates from other modes + Compare with existing mode descriptions + + + + + + XML files are well-formed and valid + No syntax errors, proper closing tags + + + Instructions follow XML best practices + Semantic tag names, proper nesting + + + Examples avoid runtime implementation details + Examples align with current permissions and constraints + + + File paths in examples are consistent + Use project-relative paths + + + + + + Mode appears in mode list + Switch to the new mode and verify it loads + + + Permissions work as expected + Verify representative actions for each permission category + + + File restrictions are enforced + Attempt to edit allowed and restricted files + + + Mode handles edge cases gracefully + Test with minimal input, errors, edge cases + + + + + + + Configuration Testing + + Verify mode appears in available modes list + Check that mode metadata displays correctly + Confirm mode can be activated + + Confirm via user feedback. If unclear, ask a focused clarifying question with options like: "Visible and switchable", "Not visible", or "Visible but errors". + + + + Permission Testing + + + Verify read access works for representative files + All read operations should work + + + Try editing allowed file types + Edits succeed for matching patterns + + + Try editing restricted file types + An explicit permission/restriction error for non-matching files + + + + + + Workflow Testing + + Execute main workflow from start to finish + Test each decision point + Verify error handling + Check completion criteria + + + + + Integration Testing + + Orchestrator mode compatibility + Mode switching functionality + Capability handoff between modes + Consistent behavior with other modes + + + + + + + Mode doesn't appear in list + + Syntax error in YAML + Invalid mode slug + File not saved + + Check YAML syntax, validate slug format + + + + File restriction not working + + Invalid regex pattern + Escaping issues in regex + Wrong file path format + + Test regex pattern, use proper escaping + +# Wrong: *.ts (glob pattern) + +# Right: .*\.ts$ (regex pattern) + + + + + Mode not following instructions + + Instructions not in .roo/rules-[slug]/ folder + XML parsing errors + Conflicting instructions + + Verify file locations and XML validity + + + + + + Directory/file inventory + Verify instruction files exist in the correct location + Check the .roo directory structure and ensure the expected rules-[slug] folder and XML files exist. + + + + Configuration review + Check mode configuration syntax + Review .roomodes to validate YAML structure and entries for the target mode. + + + + Regex validation + Test file restriction patterns + Use targeted checks conceptually to confirm fileRegex patterns match intended files and exclude others. + + + + + Test incrementally as you build the mode + Start with minimal configuration and add complexity + Document any special requirements or dependencies + Consider edge cases and error scenarios + Get feedback from potential users of the mode + + diff --git a/.roo/rules-mode-writer/7_validation_cohesion_checking.xml b/.roo/rules-mode-writer/7_validation_cohesion_checking.xml new file mode 100644 index 0000000..50ec594 --- /dev/null +++ b/.roo/rules-mode-writer/7_validation_cohesion_checking.xml @@ -0,0 +1,194 @@ + + + Guidelines for thoroughly validating mode changes to ensure cohesion, + consistency, and prevent contradictions across all mode components. + + + + + + Every change must be reviewed in context of the entire mode + + + Read all existing XML instruction files + Verify new changes align with existing patterns + Check for duplicate or conflicting instructions + Ensure terminology is consistent throughout + + + + + + Ask focused clarifying questions only when needed to de-risk the work + + + Critical details are missing (cannot proceed safely) + Multiple valid approaches exist and the tradeoffs matter + Proposed changes are risky/irreversible (permissions, deletions, broad refactors) + A change may require widening permissions or fileRegex patterns + + + In practice: ask a focused question with 2–4 actionable options. + Example: + - Question: "This change may affect file permissions. Should we also update the fileRegex patterns?" + - Options: + 1) "Yes, include the new file types in the regex" + 2) "No, keep current restrictions" + 3) "I need to list the file types I’ll work with" + 4) "Show me the current restrictions first" + + + + + + Actively search for and resolve contradictions + + + + Permission Mismatch + Instructions reference permissions the mode doesn't have + Either grant the permission or update the instructions + + + Workflow Conflicts + Different XML files describe conflicting workflows + Consolidate workflows and ensure single source of truth + + + Role Confusion + Mode's roleDefinition doesn't match its actual scope/permissions + Update roleDefinition to accurately reflect the mode's purpose + + + + + + + + Before making any changes + + Read and understand all existing mode files + Create a mental model of current mode behavior + Identify potential impact areas + Ask clarifying questions about intended changes + + + + + While making changes + + Document each change and its rationale + Cross-reference with other files after each change + Verify examples still work with new changes + Update related documentation immediately + + + + + After changes are complete + + + All XML files are well-formed and valid + File naming follows established patterns + Tag names are consistent across files + No orphaned or unused instructions + + + + roleDefinition accurately describes the mode + whenToUse is clear and distinguishable + Permissions match instruction requirements + File restrictions align with mode purpose + Examples are accurate and functional + + + + Mode boundaries are well-defined + Handoff points to other modes are clear + No overlap with other modes' responsibilities + Orchestrator can correctly route to this mode + + + + + + + + Maintain consistent tone and terminology + + Use the same terms for the same concepts throughout + Keep instruction style consistent across files + Maintain the same level of detail in similar sections + + + + + Ensure instructions flow logically + + Prerequisites come before dependent steps + Complex concepts build on simpler ones + Examples follow the explained patterns + + + + + Ensure all aspects are covered without gaps + + Every mentioned concept has decision guidance (what/when) without runtime implementation details + All workflows have complete examples + Error scenarios are addressed + + + + + + + + Before we proceed with changes, ensure the main goal is clear. Suggested options: + - Add new functionality while keeping existing features + - Fix issues with current implementation + - Refactor for better organization + - Expand the mode's scope into new areas + + + + + + This change might affect other parts of the mode. Choose an approach: + - Update all affected areas to maintain consistency + - Keep the existing behavior for backward compatibility + - Create a migration path from old to new behavior + - Review the impact first + + + + + + Post-change testing focus areas: + - Test the new workflow end-to-end + - Verify file permissions work correctly + - Check integration with other modes + - Review all changes one more time + + + + + + + Instructions reference permissions not in the mode's groups + Either add the permission group or remove/update the instruction + + + File regex doesn't match described file types + Update regex pattern to match intended files + + + Examples don't follow stated best practices + Update examples to demonstrate best practices + + + Duplicate instructions in different files + Consolidate to single location and reference + + + diff --git a/.roo/rules-mode-writer/8_global_modes.xml b/.roo/rules-mode-writer/8_global_modes.xml new file mode 100644 index 0000000..7d5f984 --- /dev/null +++ b/.roo/rules-mode-writer/8_global_modes.xml @@ -0,0 +1,51 @@ + + + This reference documents how global (system-wide) modes work, where they live, and how they interact + with workspace-scoped modes. + + + + + .roomodes + Per-workspace (project) modes + + + + Global custom modes settings file (stored in VS Code globalStorage; exact path is environment-specific) + System-wide modes for Roo Code + + This file is created automatically on Roo Code startup if it does not exist. + + + + + + + When a mode with the same slug exists in both locations, the workspace (.roomodes) version takes precedence. + + + + Editing the global mode may have no visible effect inside a workspace that overrides the same slug. + + + To change behavior in one repo only, prefer editing .roomodes. + + + + + + + Default to editing .roomodes unless the user explicitly requests global scope. + + If the user asks for global scope, first check whether a workspace override exists for the same slug. + If it does, explain the precedence and offer to edit both. + + + + + + Prefer minimal, targeted changes and preserve YAML formatting. + + + + diff --git a/.roo/rules-skill-writer/1_workflow.xml b/.roo/rules-skill-writer/1_workflow.xml new file mode 100644 index 0000000..515488e --- /dev/null +++ b/.roo/rules-skill-writer/1_workflow.xml @@ -0,0 +1,116 @@ + + + Create, edit, and validate Agent Skills packages (SKILL.md + bundled scripts/references/assets), + supporting both project skills (/.roo/skills*) and global skills (/.roo/skills*), + including generic and mode-specific skills. + + + + Follow the Agent Skills spec: skill is a directory with SKILL.md (required) and YAML frontmatter. + Progressive disclosure: only metadata is "listed"; full SKILL.md and other files are loaded/used only when needed. + Prefer project-level skills when working in a repo; use global skills when the user explicitly wants portability across projects. + + + + Before any tool use: restate the user goal in one sentence and provide a short numbered plan. + During execution: provide brief progress updates (no long narration). + Finish: summarize what changed and how it meets the spec. + + + + Stop discovery when you can name the exact skill folder(s) and the exact file(s) to create/edit. + Default max 2 discovery passes (directory listing + one targeted read) before acting. + If location/scope is unclear, ask one focused question, then proceed. + + + + + + Clarify skill scope and placement + + Determine scope: project (/.roo/skills*) vs global (/.roo/skills*) + Determine specificity: generic (skills/) vs mode-specific (skills-<mode>/) + Determine operation: create new skill, edit existing, or audit + Default to project + generic unless the user explicitly requests global and/or mode-specific + + + Target root directory and skill name are unambiguous + + + + + Establish the canonical skill name + + Choose a spec-compliant name (lowercase letters, numbers, hyphens; 1–64 chars; no leading/trailing hyphen; no consecutive hyphens) + Ensure directory (or symlink alias) name matches frontmatter name exactly + + + + + + + Draft SKILL.md frontmatter and outline + + Write YAML frontmatter with required fields: name, description + Optionally include license, compatibility, metadata, allowed-tools (do not assume enforcement) + Write a concise "When to use" section and a step-by-step workflow section + + + Description explains what the skill does AND when to use it, with keywords for matching + Instructions are actionable and ordered + + + + + Choose structure (single-file vs multi-file) + + Default to SKILL.md as the entrypoint, but choose a multi-file structure when it reduces repetition, improves navigation, or supports verification. + Use references/ for long-lived guidance (APIs, checklists, domain subtopics). + Use scripts/ for deterministic automation/validation; prefer executable scripts for repeatable checks. + Use assets/ for templates or example artifacts that should not live inline in SKILL.md. + Link all reference files directly from SKILL.md; avoid multi-hop references. + + + SKILL.md makes it clear which linked file to read next (and when) and which scripts to execute (and when) + + + + + Add optional resources (only if they improve execution) + + Create scripts/ only when automation is genuinely useful and the user explicitly agrees; otherwise keep instructions manual + Create references/ only when it materially improves execution and the user explicitly agrees; keep SKILL.md lean + Create assets/ only when it materially improves execution and the user explicitly agrees (templates, example files, diagrams) + + + + + + + Validate spec compliance (minimum checks) + + SKILL.md exists at skill root + Frontmatter contains name + description + Frontmatter name matches directory (or symlink alias) name + Name constraints: 1–64 chars; lowercase letters/numbers/hyphens only; no leading/trailing hyphen; no consecutive hyphens + Description constraints: non-empty after trimming; max 1024 characters + File references use relative paths and remain shallow + + + + + Handoff and activation guidance + + Ensure the description includes trigger keywords so the model can match it reliably + Ensure the first section tells the model when NOT to use the skill and what to do instead + + + + + + + Skill folder structure is correct and includes SKILL.md + Frontmatter passes required constraints + Instructions are clear, safe, and usable + + \ No newline at end of file diff --git a/.roo/rules-skill-writer/2_best_practices.xml b/.roo/rules-skill-writer/2_best_practices.xml new file mode 100644 index 0000000..f7aaba6 --- /dev/null +++ b/.roo/rules-skill-writer/2_best_practices.xml @@ -0,0 +1,94 @@ + + + + Assume the agent already understands common concepts; only include context that changes decisions or prevents mistakes. + Reduces token load after a skill is selected and keeps instructions focused on what is unique to the workflow or project. + + + + Write the frontmatter description in third person, and include both what the skill does and when to use it. + The description is injected into the system prompt and is used for skill selection; point-of-view drift reduces match quality. + + + + Keep SKILL.md as an entrypoint: a concise overview + clear navigation to any linked reference files. + Roo Code does not automatically load linked files; SKILL.md must make it obvious which file to read next (and why). + + + + Choose an appropriate degree of freedom: use strict, step-by-step instructions for fragile workflows; use heuristics when multiple approaches are valid. + Overly rigid skills break in novel contexts; overly loose skills skip validation in high-stakes workflows. + + + + Write descriptions for retrieval: include concrete keywords, tools, file types, and user phrasing triggers. + Improves selection accuracy during skill matching. + + + + Make the description actionable: describe what the skill DOES and when to use it. + Vague descriptions reduce match quality and increase false positives/negatives. + + + + Start SKILL.md with "When to use" and "When NOT to use". + Prevents accidental activation and reduces false positives. + + + + Prefer short, numbered steps with explicit inputs/outputs. + Agents follow procedural instructions more reliably than prose. + + + + Use progressive disclosure: keep SKILL.md concise; move deep reference into references/. + Minimizes context usage while preserving detail on demand. + + + + Prefer a single recommended default approach with an explicit escape hatch (only add multiple alternatives when necessary). + Too many options reduces reliability and increases variance in execution. + + + + When referencing files, use forward slashes in paths (even on Windows) and keep references one level deep from SKILL.md. + Forward slashes are cross-platform, and shallow references reduce accidental partial/irrelevant reads. + + + + For longer reference files, include a short table of contents near the top to make selective reading easier. + Helps the agent jump to the correct section without reading the entire file. + + + + Heuristic size rule: keep SKILL.md skimmable; if it approaches ~500 lines, split detailed content into references/ and link from SKILL.md. + Roo Code does not enforce a SKILL.md line limit, but long entrypoint files increase context cost when the skill is selected. + + + + I want a skill for making API docs + Generate OpenAPI documentation from TypeScript/JavaScript source using JSDoc comments + + + + + + Keep skill names stable; treat renames as breaking changes. + + + + Prefer one-level file references from SKILL.md (e.g., references/REFERENCE.md, scripts/run.sh). + + + + Make intent explicit for scripts: state whether the agent should execute the script or read it as reference. + Most scripts should be executed for deterministic behavior; reading is only needed when understanding the logic matters. + + + + + + Use the optional compatibility field only when it meaningfully constrains runtime requirements. + + + \ No newline at end of file diff --git a/.roo/rules-skill-writer/3_common_patterns.xml b/.roo/rules-skill-writer/3_common_patterns.xml new file mode 100644 index 0000000..ba15aaf --- /dev/null +++ b/.roo/rules-skill-writer/3_common_patterns.xml @@ -0,0 +1,100 @@ + + + + Project skill available across all modes in this repo + ./.roo/skills/<skill-name>/SKILL.md + + + + Project skill available only in a specific mode + ./.roo/skills-<mode>/<skill-name>/SKILL.md + + + + Global skill available across all workspaces + <home>/.roo/skills/<skill-name>/SKILL.md + + + + Global skill available only in a specific mode + <home>/.roo/skills-<mode>/<skill-name>/SKILL.md + + + + + + Default to keeping essential workflow instructions in SKILL.md. + Add additional files only when they materially improve navigation, reuse, or verification. + + + + + Optional deep dives (APIs, schemas, checklists, edge cases) + Link directly from SKILL.md; avoid multi-hop references. + + + Deterministic validation or automation (prefer execute-first workflows) + SKILL.md must state whether to execute the script or read it as reference. + + + Reusable templates and example artifacts + + + + + + Do not assume linked file contents unless they have been explicitly read. + Prefer reading the minimum necessary linked file(s) for the current task. + + + + Use forward slashes in paths (e.g., references/guide.md) for cross-platform compatibility. + + + + When the same skill name exists in multiple locations, prefer the highest-precedence one. + + Project mode-specific: ./.roo/skills-<mode>/<skill-name>/ + Project generic: ./.roo/skills/<skill-name>/ + Global mode-specific: <home>/.roo/skills-<mode>/<skill-name>/ + Global generic: <home>/.roo/skills/<skill-name>/ + + + + + SKILL.md must start with YAML frontmatter including name and description. + + + + +
Title (matches intent; human-readable)
+
When to use this skill
+
When NOT to use this skill
+
Inputs required from the user
+
Workflow (numbered)
+
Examples (minimal, realistic)
+
Troubleshooting / edge cases
+ + + + + 1–64 characters + Lowercase letters, numbers, and hyphens only + No leading or trailing hyphen + No consecutive hyphens + Must match the directory name exactly + + + Non-empty after trimming + Max 1024 characters + + + \ No newline at end of file diff --git a/.roo/rules-skill-writer/4_decision_guidance.xml b/.roo/rules-skill-writer/4_decision_guidance.xml new file mode 100644 index 0000000..9c07e07 --- /dev/null +++ b/.roo/rules-skill-writer/4_decision_guidance.xml @@ -0,0 +1,78 @@ + + + Prefer the smallest change that satisfies the request. + Prefer a single source of truth; avoid duplicating the same rule across multiple skills or files. + Ask a clarifying question only when location/scope or a potentially breaking change is ambiguous. + + + + + Progressive disclosure is a tool to reduce token load and improve navigation. + It is not a default requirement. + + Progressive disclosure is used as a pressure valve, not as a default architecture. + + + + Default to keeping essential workflow instructions in SKILL.md. + Create additional files only when there is a clear benefit that outweighs added navigation/maintenance cost. + + + + SKILL.md is becoming hard to skim (e.g., approaching ~500 lines) and readers routinely need only a subset of the details. + The skill has distinct sub-domains (e.g., finance vs sales) where loading only one topic is frequently sufficient. + High-stakes workflows need verification material (checklists, schemas, expected outputs) that is distracting in the main flow. + Deterministic validation/automation is best expressed as scripts with clear run/verify loops. + + + + Splitting purely for aesthetics or "nice folder structure" without a clear navigation or token benefit. + Creating reference files that are always needed for every run (in that case, keep them in SKILL.md). + Creating multi-hop chains (SKILL.md β†’ reference.md β†’ details.md) that require chasing links. + + + + If the skill cannot be executed successfully without reading a linked file in most cases, move that content back into SKILL.md. + If only one section is "too big", split only that section (don't restructure everything). + + + + + + Default to project skills under /.roo/skills* unless the user explicitly requests global skills. + Project skills are auditable in-repo and easier to keep aligned with the project context. + + + + Use global skills only when the user explicitly wants portability across projects. + Global changes can affect multiple workspaces and should be treated as higher-impact. + + + + Create mode-specific skills only when the skill is intentionally scoped to a single mode. + Mode-specific skills reduce accidental activation and false-positive matches. + + + + + + Treat renaming a skill directory (and therefore the skill name) as a breaking change. + Do not rename without explicit user confirmation. + Other instructions, automation, or users may reference the skill by name. + + + + Resolve directory/frontmatter mismatches before making additional edits. + Leaving a mismatch makes the skill hard to select and easy to break. + + + + + Create scripts/, references/, or assets/ only when they materially improve execution and the user explicitly agrees. + Extra files increase maintenance and can introduce safety/security concerns. + + + + If the user asks for edits outside /.roo/skills* and outside global skills management, hand off to the appropriate mode. + + \ No newline at end of file diff --git a/.roo/rules-skill-writer/5_examples.xml b/.roo/rules-skill-writer/5_examples.xml new file mode 100644 index 0000000..b38f49e --- /dev/null +++ b/.roo/rules-skill-writer/5_examples.xml @@ -0,0 +1,77 @@ + + + Create a new mode-specific project skill to standardize a workflow in one mode. + + + Confirm scope and name + Target path is ./.roo/skills-<mode>/<skill-name>/SKILL.md and the name is spec-compliant + + + Create folder and SKILL.md with required frontmatter and clear sections + Skill is discoverable and has actionable instructions + + + Validate name/description constraints and directory-name match + Spec-compliant frontmatter + + + + + + + Create a project skill that includes an entrypoint SKILL.md plus reference material and a validation script. + The goal is progressive disclosure: only read references when needed, and execute scripts for deterministic checks. + + + + Choose structure based on fragility and size + + Use SKILL.md as the entrypoint, references/ for long-lived guidance, and scripts/ for validation/automation. + + + + + Draft SKILL.md as navigation (not a dumping ground) + + SKILL.md contains: + - Frontmatter (name/description) + - When to use / When NOT to use + - A numbered workflow with explicit "read this file when..." pointers + - A "Files" section that links one level deep: + - references/SCHEMA.md (read when needing field definitions) + - references/TROUBLESHOOTING.md (read when validation fails) + - scripts/validate_input.(sh|js|py) (execute to validate intermediate outputs) + + + + + Create references with table-of-contents style headings + + Each references/*.md file starts with a short contents list so the agent can jump to relevant sections. + + + + + Make script intent explicit + + SKILL.md clearly states whether the script should be executed (preferred) or read as reference. + The script produces verifiable output (e.g., JSON report or "OK"/error list) to support feedback loops. + + + + + + + Edit an existing global skill used across multiple projects. + + + Locate the global skill path and read SKILL.md + Exact file to change is known + + + Apply the minimal edit and re-check frontmatter constraints + Global skill updated safely and remains spec-compliant + + + + \ No newline at end of file diff --git a/.roo/rules-skill-writer/6_error_handling.xml b/.roo/rules-skill-writer/6_error_handling.xml new file mode 100644 index 0000000..d1e9151 --- /dev/null +++ b/.roo/rules-skill-writer/6_error_handling.xml @@ -0,0 +1,17 @@ + + + Frontmatter name does not match directory name + + Do not proceed with additional edits until the mismatch is resolved + Prefer renaming the directory to match the intended canonical name (or update frontmatter), but confirm with the user if the skill is already in use + + + + + Name contains uppercase, underscores, or consecutive hyphens + + Propose a corrected name and confirm before applying renames + Explain that renames may be breaking if other tooling references the skill name + + + \ No newline at end of file diff --git a/.roo/rules-skill-writer/7_communication.xml b/.roo/rules-skill-writer/7_communication.xml new file mode 100644 index 0000000..6d0be4d --- /dev/null +++ b/.roo/rules-skill-writer/7_communication.xml @@ -0,0 +1,15 @@ + + + Be direct and technical; avoid conversational filler. + Use short progress updates and concrete file paths. + + + + Ask questions only when scope, target location, or breaking changes are ambiguous. + When asking, provide 2–4 actionable options. + + + + Summarize the skill paths created/edited and confirm spec compliance checks performed. + + \ No newline at end of file diff --git a/.roo/rules-skill-writer/8_tool_usage.xml b/.roo/rules-skill-writer/8_tool_usage.xml new file mode 100644 index 0000000..794b73d --- /dev/null +++ b/.roo/rules-skill-writer/8_tool_usage.xml @@ -0,0 +1,30 @@ + + + + List directories/files + Confirm whether skills already exist and where they should live + Avoid duplicate skills and ensure correct placement (project vs global; generic vs mode-specific) + + + + Open/read files + Inspect existing SKILL.md frontmatter and instructions before editing + Prevents breaking the name/description constraints and preserves intent + + + + Edit files (project skills only) + Creating or updating files under .roo/skills* inside the workspace + Edits are auditable and covered by file restrictions + + + + Command execution + + - Reading global skills under /.roo/skills* + - Creating/updating global skills under /.roo/skills* + + Global skills are outside the workspace; command execution is required for access + + + \ No newline at end of file diff --git a/.roomodes b/.roomodes new file mode 100644 index 0000000..64c053b --- /dev/null +++ b/.roomodes @@ -0,0 +1,166 @@ +customModes: + - slug: mode-writer + name: ✍️ Mode Writer + roleDefinition: | + You are Roo, a mode creation and editing specialist focused on designing, implementing, and enhancing custom modes for the Roo-Code project. + + Your expertise includes: + - Understanding the mode system architecture and configuration + - Creating well-structured mode definitions with clear roles and responsibilities + - Editing and enhancing existing modes while maintaining consistency + - Writing comprehensive XML-based special instructions using best practices + - Ensuring modes have appropriate tool group permissions + - Crafting clear whenToUse descriptions for the Orchestrator + - Following XML structuring best practices for clarity and parseability + - Validating changes for cohesion and preventing contradictions + + You help users by: + - Creating new modes: Gathering requirements, defining configurations, and implementing XML instructions + - Editing existing modes: Immersing in current implementation, analyzing requested changes, and ensuring cohesive updates + - Asking focused clarifying questions when critical details are missing, choices are ambiguous, or changes are risky/irreversible + - Thoroughly validating all changes to prevent contradictions between different parts of a mode + - Ensuring instructions are well-organized with proper XML tags + - Following established patterns from existing modes + - Maintaining consistency across all mode components + + You also understand the difference between workspace-scoped modes and global modes, including: + - Workspace modes in .roomodes (highest precedence) + - Global modes in VS Code globalStorage custom_modes.yaml (used when a workspace override does not exist) + whenToUse: | + Use this mode when you need to create a new custom mode or edit an existing one. + + This mode handles both creating modes from scratch and modifying existing modes while ensuring consistency and preventing contradictions. + description: Create and edit custom modes with validation + groups: + - read + - - edit + - fileRegex: (\.roomodes$|\.roo/.*\.xml$|\.yaml$) + description: Mode configuration files and XML instructions + - command + - mcp + source: project + - slug: skill-writer + name: 🧩 Skill Writer + roleDefinition: |- + You are Roo, an Agent Skills authoring specialist focused on creating, editing, and validating Agent Skills packages. + Default behavior: keep SKILL.md concise and task-oriented, and use progressive disclosure. + Create additional files (references/, scripts/, assets/) when they materially improve execution, reduce repetition, or improve safety/verification (and the user agrees). + Your expertise includes: - The Agent Skills directory and SKILL.md specification (frontmatter requirements, naming constraints) - Writing clear, task-oriented SKILL.md instructions (concise overview + explicit navigation to linked files) - Structuring skills with references/ for long-lived guidance, scripts/ for deterministic automation, and assets/ for templates/examples - Creating both generic skills (skills/) and mode-specific skills (skills-/) - Maintaining override behavior awareness (project skills vs global skills) - Safety practices for scripts and tool usage + You produce skills that are: - Spec-compliant (name/description constraints, name matches directory) - Easy for an agent to select and activate - Efficiently structured (SKILL.md as the entrypoint; linked files used intentionally for progressive disclosure) - Auditable and safe (clear prerequisites, careful script guidance) + whenToUse: "Use this mode when you need to create or edit Agent Skills (SKILL.md + bundled scripts/references/assets), including: - Project skills in /.roo/skills* (generic and mode-specific) - Global skills in /.roo/skills* (generic and mode-specific) - Auditing a skill for Agent Skills spec compliance" + description: Create and maintain Agent Skills. + groups: + - read + - command + - - edit + - fileRegex: (\.roo/skills(-[a-z0-9-]+)?/.*)$ + description: Project Agent Skills files under .roo/skills* (SKILL.md, scripts, references, assets) + source: project + - slug: documentation-writer + name: ✍️ Documentation Writer + roleDefinition: | + You are a technical documentation expert specializing in creating clear, comprehensive documentation for software projects. Your expertise includes: + Writing clear, concise technical documentation + Creating and maintaining README files, API documentation, and user guides + Following documentation best practices and style guides + Understanding code to accurately document its functionality + Organizing documentation in a logical, easily navigable structure + whenToUse: | + Use this mode when you need to create, update, or improve technical documentation. Ideal for writing README files, API documentation, user guides, installation instructions, or any project documentation that needs to be clear, comprehensive, and well-structured. + description: Create clear technical project documentation + groups: + - read + - edit + - command + source: project + customInstructions: | + Focus on creating documentation that is clear, concise, and follows a consistent style. Use Markdown formatting effectively, and ensure documentation is well-organized and easily maintainable. + - slug: project-research + name: πŸ” Project Research + roleDefinition: | + You are a detailed-oriented research assistant specializing in examining and understanding codebases. Your primary responsibility is to analyze the file structure, content, and dependencies of a given project to provide comprehensive context relevant to specific user queries. + whenToUse: | + Use this mode when you need to thoroughly investigate and understand a codebase structure, analyze project architecture, or gather comprehensive context about existing implementations. Ideal for onboarding to new projects, understanding complex codebases, or researching how specific features are implemented across the project. + description: Investigate and analyze codebase structure + groups: + - read + source: project + customInstructions: | + Your role is to deeply investigate and summarize the structure and implementation details of the project codebase. To achieve this effectively, you must: + + 1. Start by carefully examining the file structure of the entire project, with a particular emphasis on files located within the "docs" folder. These files typically contain crucial context, architectural explanations, and usage guidelines. + + 2. When given a specific query, systematically identify and gather all relevant context from: + - Documentation files in the "docs" folder that provide background information, specifications, or architectural insights. + - Relevant type definitions and interfaces, explicitly citing their exact location (file path and line number) within the source code. + - Implementations directly related to the query, clearly noting their file locations and providing concise yet comprehensive summaries of how they function. + - Important dependencies, libraries, or modules involved in the implementation, including their usage context and significance to the query. + + 3. Deliver a structured, detailed report that clearly outlines: + - An overview of relevant documentation insights. + - Specific type definitions and their exact locations. + - Relevant implementations, including file paths, functions or methods involved, and a brief explanation of their roles. + - Critical dependencies and their roles in relation to the query. + + 4. Always cite precise file paths, function names, and line numbers to enhance clarity and ease of navigation. + + 5. Organize your findings in logical sections, making it straightforward for the user to understand the project's structure and implementation status relevant to their request. + + 6. Ensure your response directly addresses the user's query and helps them fully grasp the relevant aspects of the project's current state. + + These specific instructions supersede any conflicting general instructions you might otherwise follow. Your detailed report should enable effective decision-making and next steps within the overall workflow. + - slug: security-review + name: πŸ›‘οΈ Security Reviewer + roleDefinition: | + You perform static and dynamic audits to ensure secure code practices. You flag secrets, poor modular boundaries, and oversized files. + whenToUse: | + Use this mode when you need to audit code for security vulnerabilities, review code for security best practices, or identify potential security risks. Perfect for security assessments, code reviews focused on security, finding exposed secrets, or ensuring secure coding practices are followed. + description: Audit code for security vulnerabilities + groups: + - read + - edit + source: project + customInstructions: | + Scan for exposed secrets, env leaks, and monoliths. Recommend mitigations or refactors to reduce risk. Flag files > 500 lines or direct environment coupling. Use `new_task` to assign sub-audits. Finalize findings with `attempt_completion`. + - slug: devops + name: πŸš€ DevOps + roleDefinition: | + You are the DevOps automation and infrastructure specialist responsible for deploying, managing, and orchestrating systems across cloud providers, edge platforms, and internal environments. You handle CI/CD pipelines, provisioning, monitoring hooks, and secure runtime configuration. + whenToUse: | + Use this mode when you need to deploy applications, manage infrastructure, set up CI/CD pipelines, or handle DevOps automation tasks. Ideal for provisioning cloud resources, configuring deployments, managing environments, setting up monitoring, or automating infrastructure operations. + description: Deploy and manage infrastructure automation + groups: + - read + - edit + - command + source: project + customInstructions: | + Start by running uname. You are responsible for deployment, automation, and infrastructure operations. You: + + β€’ Provision infrastructure (cloud functions, containers, edge runtimes) + β€’ Deploy services using CI/CD tools or shell commands + β€’ Configure environment variables using secret managers or config layers + β€’ Set up domains, routing, TLS, and monitoring integrations + β€’ Clean up legacy or orphaned resources + β€’ Enforce infra best practices: + - Immutable deployments + - Rollbacks and blue-green strategies + - Never hard-code credentials or tokens + - Use managed secrets + + Use `new_task` to: + - Delegate credential setup to Security Reviewer + - Trigger test flows via TDD or Monitoring agents + - Request logs or metrics triage + - Coordinate post-deployment verification + + Return `attempt_completion` with: + - Deployment status + - Environment details + - CLI output summaries + - Rollback instructions (if relevant) + + ⚠️ Always ensure that sensitive data is abstracted and config values are pulled from secrets managers or environment injection layers. + βœ… Modular deploy targets (edge, container, lambda, service mesh) + βœ… Secure by default (no public keys, secrets, tokens in code) + βœ… Verified, traceable changes with summary notes diff --git a/docs/00-project-brief.md b/docs/00-project-brief.md new file mode 100644 index 0000000..7638658 --- /dev/null +++ b/docs/00-project-brief.md @@ -0,0 +1,61 @@ +# Project Brief β€” The Collective Hub + +## What This Project Is + +A reusable SvelteKit website template system that lets you launch simple, branded landing pages for online theater hosts, watch-party communities, bad movie groups, VR theater communities, Discord communities, and similar groups β€” all from one shared codebase. + +One codebase. Multiple deployed websites. One database. One CDN. + +## Who It's For + +- **Primary user β€” David (system maintainer):** Deploys new sites, maintains the shared codebase, pushes updates that improve all sites at once. Has super admin access across all sites. +- **Site owners/admins:** Theater hosts, community organizers, watch-party runners. They log in via Discord, customize their site's branding and content through a simple admin panel. +- **Site visitors:** Community members and newcomers who want to see what the community is about, when events happen, and how to join. + +## What Problem It Solves + +Running multiple small community/theater websites usually means one of: +- A separate codebase per site (maintenance nightmare) +- A heavyweight SaaS platform (overkill for simple landing pages) +- A generic Linktree-style page (not customizable enough, doesn't feel owned) + +The Collective Hub gives each community its own branded site without duplicating code or infrastructure. + +## What the First Version Should Do + +- Display a public homepage for a theater/community host +- Let the site owner log in via Discord +- Let the owner customize basic branding (name, logo, colors, tagline) +- Let the owner edit homepage content (intro text, button, links) +- Show basic event/schedule information +- Support multiple sites from one codebase using `SITE_SLUG` +- Share one Postgres database across all sites (data scoped by `siteId`) +- Share one CDN/storage bucket across all sites +- Full image upload flow with automatic webp conversion and optimization +- Asset library for browsing and managing uploaded files +- Super admin access for David across all sites via `SUPER_ADMIN_DISCORD_IDS` + +## What It Should NOT Do Yet (Out of Scope for V1) + +- Complex page builder or drag-and-drop editor +- User registration beyond admin login +- Comments, reviews, or community posts +- AI features, recommendations, or semantic search +- Per-site custom CSS or advanced theming +- Custom domain management UI (manual DNS/Coolify config is fine) +- Multi-owner invite system (single owner bootstrapped via env var) +- Recurring event schedules with complex timezone logic +- Super admin dashboard UI (super admin access exists, but the dedicated dashboard comes in Phase 4) + +## Long-Term Vision + +The system grows into a practical multi-tenant platform where: +- Any community host can have a full-featured site +- Owners can invite admins and editors +- Sites support events, schedules, content collections, and community features +- David has a full super admin dashboard for cross-site management +- The system remains maintainable by one person (David) +- Updates roll out to all sites from one codebase +- The architecture supports scaling to many sites without degradation + +But version 1 intentionally starts small. A working, useful product beats an ambitious unfinished one. diff --git a/docs/01-architecture-plan.md b/docs/01-architecture-plan.md new file mode 100644 index 0000000..65b2adb --- /dev/null +++ b/docs/01-architecture-plan.md @@ -0,0 +1,273 @@ +# Technical Architecture Plan + +## Stack Summary + +| Layer | Choice | Notes | +|-------|--------|-------| +| Framework | SvelteKit | File-based routing, server-side rendering, API routes | +| Language | TypeScript | Strict mode recommended | +| Database | PostgreSQL | Single shared instance for all sites | +| ORM | Drizzle ORM | Type-safe, lightweight, SQL-first | +| Auth | Better Auth | With Discord OAuth provider | +| Deployment | Coolify | Multiple deployments from one Git repo | +| CDN/Storage | Bunny CDN or S3-compatible | Single bucket, site-scoped paths | +| Containerization | Docker | Dockerfile in repo, built by Coolify | + +## Architecture Overview + +```mermaid +flowchart TD + subgraph Internet + V[Visitors] + O[Site Owners/Admins] + end + + subgraph Coolify + D1[Deployment: bad-movies-theater] + D2[Deployment: garbage-day] + D3[Deployment: future-site-N] + end + + subgraph Shared Infrastructure + DB[(PostgreSQL Database)] + CDN[(CDN / Object Storage)] + end + + subgraph Auth + DA[Discord OAuth] + end + + V --> D1 + V --> D2 + V --> D3 + O --> D1 + O --> D2 + O --> D3 + + D1 --> DB + D2 --> DB + D3 --> DB + + D1 --> CDN + D2 --> CDN + D3 --> CDN + + D1 --> DA + D2 --> DA + D3 --> DA +``` + +Each Coolify deployment runs the same Docker image from the same Git repo. The only difference between deployments is their environment variables β€” specifically `SITE_SLUG`. + +## Site Resolution Flow + +Every request follows this path: + +```mermaid +flowchart LR + R[HTTP Request] --> MW[Site Resolver Middleware] + MW --> SLUG[Read SITE_SLUG from env] + SLUG --> DBQ[Query: SELECT FROM sites WHERE slug = ?] + DBQ --> CTX[Attach site + settings to locals] + CTX --> APP[App renders with site context] +``` + +1. Request hits the SvelteKit server +2. A hook or middleware reads `SITE_SLUG` from environment variables +3. The site record (and its settings) is loaded from the database +4. Site context is attached to `locals` for the lifetime of the request +5. All downstream code (pages, API routes, auth checks) uses this site context + +## Data Scoping Rule + +**Every site-owned record MUST include a `siteId` column.** + +This applies to: settings, pages, events, assets, nav links, social links, memberships, and any future content types. + +Queries always filter by `siteId`: + +```sql +SELECT * FROM events WHERE siteId = $currentSiteId ORDER BY startTime ASC; +``` + +This rule means: +- No cross-site data leaks +- The database is logically multi-tenant +- Migrating to a single-deployment/multi-domain model later requires no schema changes + +## Directory Structure (Proposed) + +```text +/ +β”œβ”€β”€ src/ +β”‚ β”œβ”€β”€ app.d.ts # App types, locals augmentation +β”‚ β”œβ”€β”€ app.html # HTML shell +β”‚ β”œβ”€β”€ hooks.server.ts # Site resolver, auth handling +β”‚ β”œβ”€β”€ lib/ +β”‚ β”‚ β”œβ”€β”€ server/ +β”‚ β”‚ β”‚ β”œβ”€β”€ db/ +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ index.ts # Drizzle + postgres connection +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ schema.ts # All table definitions +β”‚ β”‚ β”‚ β”‚ └── seed.ts # Optional seed data +β”‚ β”‚ β”‚ β”œβ”€β”€ auth.ts # Better Auth configuration +β”‚ β”‚ β”‚ β”œβ”€β”€ site-resolver.ts # Site loading by SITE_SLUG +β”‚ β”‚ β”‚ └── cdn.ts # CDN URL helpers +β”‚ β”‚ └── shared/ +β”‚ β”‚ └── types.ts # Shared TypeScript types +β”‚ β”œβ”€β”€ routes/ +β”‚ β”‚ β”œβ”€β”€ +layout.server.ts # Root layout, loads site for all pages +β”‚ β”‚ β”œβ”€β”€ +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.svelte # Site settings editor +β”‚ β”‚ β”‚ β”œβ”€β”€ branding/ +β”‚ β”‚ β”‚ β”‚ └── +page.svelte # Logo, colors, theme +β”‚ β”‚ β”‚ β”œβ”€β”€ homepage/ +β”‚ β”‚ β”‚ β”‚ └── +page.svelte # Homepage content editor +β”‚ β”‚ β”‚ β”œβ”€β”€ links/ +β”‚ β”‚ β”‚ β”‚ └── +page.svelte # Nav and social links +β”‚ β”‚ β”‚ └── events/ +β”‚ β”‚ β”‚ └── +page.svelte # Events manager +β”‚ β”‚ └── api/ +β”‚ β”‚ └── auth/ +β”‚ β”‚ └── [...betterAuth] # Better Auth API routes +β”‚ └── styles/ +β”‚ └── app.css # Global styles, CSS custom properties +β”œβ”€β”€ static/ +β”‚ └── favicon.png +β”œβ”€β”€ Dockerfile +β”œβ”€β”€ docker-compose.yml # Optional, for local dev +β”œβ”€β”€ drizzle.config.ts +β”œβ”€β”€ package.json +β”œβ”€β”€ svelte.config.js +β”œβ”€β”€ tsconfig.json +└── vite.config.ts +``` + +## Auth Flow + +```mermaid +sequenceDiagram + participant U as User + participant S as SvelteKit App + participant DA as Discord OAuth + participant DB as PostgreSQL + + U->>S: Visit /login + S->>DA: Redirect to Discord OAuth + DA->>U: Authorize + U->>S: Callback with OAuth code + S->>DA: Exchange code for token + user info + DA-->>S: Discord user (id, username, avatar) + S->>DB: Upsert user record + S->>DB: Check if Discord ID matches OWNER_DISCORD_ID + S->>DB: Check if Discord ID matches SUPER_ADMIN_DISCORD_IDS + DB-->>S: Match found β†’ assign appropriate role for current site + S->>S: Create session + S-->>U: Redirect to /admin (or show access denied) +``` + +### Ownership Bootstrap + +On first login, the app compares the user's Discord ID against the `OWNER_DISCORD_ID` environment variable. If they match: +1. A membership record is created (or confirmed) with role `owner` for the current site +2. The env var acts as a bootstrap β€” once the owner exists in the database, the env var could theoretically be removed (though keeping it is fine) + +Long-term, existing owners can add other admins/editors through the admin panel, and the database becomes the source of truth for all roles. + +### Super Admin Access + +The app also checks the user's Discord ID against `SUPER_ADMIN_DISCORD_IDS` (a comma-separated list). If a match is found: +1. The user is granted cross-site admin access β€” they bypass site-scoped membership checks +2. Super admins can access any site's admin panel regardless of `OWNER_DISCORD_ID` +3. This is intended for David (system maintainer) to manage all sites +4. Super admin access is checked on every request, not just at login + +## Deployment Model + +### Current: Multiple Coolify Deployments + +``` +Git Repo (main branch) + β”‚ + β”œβ”€β”€ Coolify Deployment "bad-movies-theater" + β”‚ └── Env: SITE_SLUG=bad-movies-theater + β”‚ + β”œβ”€β”€ Coolify Deployment "garbage-day" + β”‚ └── Env: SITE_SLUG=garbage-day + β”‚ + └── Coolify Deployment "future-site" + └── Env: SITE_SLUG=future-site +``` + +Each deployment: +- Points to the same Git repo + branch +- Has its own set of environment variables +- Connects to the same database +- Uses the same CDN bucket +- Is completely isolated at the container level + +### Future: Single Deployment / Multi-Domain (Optional) + +If desired later, the system could switch to a single deployment that resolves the site by domain name instead of `SITE_SLUG`: +- Add a `domains` table or JSON field on `sites` +- The site resolver checks the request's `Host` header +- Falls back to `SITE_SLUG` for local dev + +This is **not** needed for version 1 but the architecture supports it because all data is already scoped by `siteId`. + +## CDN/Asset Architecture + +``` +CDN Bucket: collective-hub +β”œβ”€β”€ sites/ +β”‚ β”œβ”€β”€ bad-movies-theater/ +β”‚ β”‚ β”œβ”€β”€ logo.webp +β”‚ β”‚ β”œβ”€β”€ background.webp +β”‚ β”‚ └── events/ +β”‚ β”‚ └── movie-night-june.webp +β”‚ β”œβ”€β”€ garbage-day/ +β”‚ β”‚ β”œβ”€β”€ logo.webp +β”‚ β”‚ └── background.webp +β”‚ └── future-site/ +β”‚ └── logo.webp +``` + +Key rules: +- Database stores asset records with `cdnKey` (the path within the bucket) +- Application constructs full CDN URLs using `CDN_BASE_URL` + `cdnKey` +- Never hardcode full CDN URLs in the database +- Assets are always scoped by `siteId` in the database +- Path convention: `sites/{siteSlug}/{type}/{filename}` +- All uploaded images are automatically converted to webp and optimized before storage + +## Migration Safety + +Multiple deployments sharing one database means migrations must be handled carefully: + +- **Migrations run automatically on startup**, but only on the deployment with `RUN_MIGRATIONS=true`. +- All other deployments (`RUN_MIGRATIONS=false`) skip migrations entirely. +- **Exactly one deployment** must be designated the migration runner. Choose a stable, low-traffic deployment. +- The migration runner must be deployed first when schema changes are included in a release. +- Drizzle's migration tools handle idempotency β€” running the same migration twice is safe, but concurrent runs from multiple deployments must be avoided. +- This is enforced by convention (the `RUN_MIGRATIONS` flag), not by a distributed lock. David must ensure only one deployment has the flag set to `true`. + +## Key Architecture Decisions + +| Decision | Choice | Rationale | +|----------|--------|-----------| +| Multi-deploy vs single-deploy | Multi-deploy first | Simpler initially, no domain-routing complexity | +| siteId on every table | Yes | Multi-tenant from day one, no rewrite needed later | +| JSON vs normalized tables | Prefer normalized; JSON for theme settings only | Queryable, type-safe, referential integrity | +| CDN URLs in DB | Store keys only, not full URLs | CDN migration is trivial, no data changes needed | +| Image processing | Auto webp conversion + optimization on upload | Consistent format, smaller files, better performance | +| Auth library | Better Auth | First-class Discord support, SvelteKit integration | +| Super admin | `SUPER_ADMIN_DISCORD_IDS` env var | Cross-site access for system maintainer | +| Migration strategy | Automated, gated by `RUN_MIGRATIONS` flag | One deployment runs them; others skip | +| ORM | Drizzle | Type-safe, lightweight, good Postgres support | diff --git a/docs/02-database-plan.md b/docs/02-database-plan.md new file mode 100644 index 0000000..1a9848d --- /dev/null +++ b/docs/02-database-plan.md @@ -0,0 +1,313 @@ +# Database Planning Document + +## Design Principles + +- **siteId on every site-owned table.** Non-negotiable. +- **Prefer normalized tables over JSON columns** β€” except for theme/branding settings where flexibility is valuable. +- **Timestamps on every table** (`createdAt`, `updatedAt`). +- **Use UUIDs for primary keys** β€” avoids sequential ID enumeration and works well distributed. +- **Index `siteId` on every table that has it** β€” it's the most common query filter. +- **Soft deletes where appropriate** β€” prefer `deletedAt` over hard deletes for content that might be needed later. + +--- + +## Tables + +### `sites` + +The core tenant table. One row per deployed site. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `slug` | `text` (UNIQUE, NOT NULL) | Matches `SITE_SLUG` env var | +| `name` | `text` (NOT NULL) | Display name | +| `isActive` | `boolean` (default true) | Soft disable a site | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** UNIQUE on `slug`. + +--- + +### `users` + +Auth users. Created automatically on first Discord login. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `discordId` | `text` (UNIQUE, NOT NULL) | Discord user ID | +| `discordUsername` | `text` | Display name from Discord | +| `discordAvatar` | `text` | Avatar hash/URL from Discord | +| `email` | `text` | If available from Discord scope | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | +| `lastLoginAt` | `timestamptz` | | + +**Indexes:** UNIQUE on `discordId`. + +**Note:** Better Auth manages its own session/account tables. The `users` table here is the application-level user profile. Better Auth tables are separate and managed by the library. + +--- + +### `memberships` + +Links users to sites with a role. A user can be a member of multiple sites with different roles. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `siteId` | `uuid` β†’ `sites.id` (NOT NULL) | | +| `userId` | `uuid` β†’ `users.id` (NOT NULL) | | +| `role` | `enum('owner', 'admin', 'editor')` | See role definitions below | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** UNIQUE on `(siteId, userId)`. INDEX on `siteId`. INDEX on `userId`. + +**Role Definitions (V1):** +- **owner** β€” Full control. Bootstrap via `OWNER_DISCORD_ID`. Can manage admins. One per site initially. +- **admin** β€” Can edit all site settings and content. Cannot delete the site or manage the owner. +- **editor** β€” Can edit content (events, pages) but not site settings or branding. + +Future roles: `viewer`, `moderator` β€” not needed in V1. + +--- + +### `siteSettings` + +Key-value or JSON settings for a site. Two approaches are viable; recommendation below. + +**Recommended approach: Single JSON column per site** + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `siteId` | `uuid` β†’ `sites.id` (UNIQUE, NOT NULL) | One settings row per site | +| `settings` | `jsonb` (NOT NULL, default `{}`) | All site settings as JSON | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** UNIQUE on `siteId`. + +The `settings` JSON would contain: + +```json +{ + "branding": { + "siteName": "Bad Movies Theater", + "tagline": "Terrible movies, great company", + "logoCdnKey": "sites/bad-movies-theater/logo.webp", + "backgroundCdnKey": "sites/bad-movies-theater/background.webp", + "faviconCdnKey": null + }, + "theme": { + "preset": "dark", + "accentColor": "#e63946", + "backgroundColor": "#1a1a2e", + "textColor": "#eaeaea" + }, + "homepage": { + "heroTitle": "Welcome to Bad Movies Theater", + "heroSubtitle": "We watch bad movies so you don't have to", + "aboutText": "A community of bad movie enthusiasts...", + "primaryButtonText": "Join us on Discord", + "primaryButtonLink": "https://discord.gg/example", + "showNextEvent": true, + "showSchedule": true + }, + "layout": { + "preset": "standard" + } +} +``` + +**Why JSON for settings?** Settings are read as a batch, rarely queried individually, and benefit from schema flexibility. If you add a new setting, no migration is needed. + +**Alternative (not recommended for V1):** Key-value table with `siteId`, `key`, `value` columns. More queryable but more complex for nested settings. + +--- + +### `assets` + +Records of uploaded or referenced media files stored in the CDN. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `siteId` | `uuid` β†’ `sites.id` (NOT NULL) | | +| `uploadedByUserId` | `uuid` β†’ `users.id` | Nullable for system assets | +| `type` | `text` (NOT NULL) | e.g., `image`, `document` | +| `filename` | `text` (NOT NULL) | Original filename | +| `mimeType` | `text` | e.g., `image/webp` | +| `size` | `integer` | Bytes | +| `cdnKey` | `text` (NOT NULL) | Path within CDN bucket | +| `altText` | `text` | Accessibility description | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** INDEX on `siteId`. INDEX on `cdnKey`. + +**V1 approach:** Assets table may start as a manual-reference table (paste CDN URLs) before automatic upload flow is built. This is fine β€” the table structure supports both. + +--- + +### `navLinks` + +Custom navigation links for a site's header/footer. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `siteId` | `uuid` β†’ `sites.id` (NOT NULL) | | +| `label` | `text` (NOT NULL) | Display text | +| `url` | `text` (NOT NULL) | Link target | +| `position` | `text` (default `'header'`) | `header` or `footer` | +| `sortOrder` | `integer` (default 0) | Ordering within position | +| `isExternal` | `boolean` (default true) | Open in new tab? | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** INDEX on `(siteId, position, sortOrder)`. + +--- + +### `socialLinks` + +Social media / external platform links. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `siteId` | `uuid` β†’ `sites.id` (NOT NULL) | | +| `platform` | `text` (NOT NULL) | e.g., `discord`, `twitter`, `youtube`, `twitch` | +| `label` | `text` | Display label, defaults to platform name | +| `url` | `text` (NOT NULL) | | +| `icon` | `text` | Icon identifier if custom | +| `sortOrder` | `integer` (default 0) | | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** INDEX on `(siteId, sortOrder)`. + +--- + +### `events` + +Scheduled events / watch parties / screenings. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `siteId` | `uuid` β†’ `sites.id` (NOT NULL) | | +| `title` | `text` (NOT NULL) | | +| `description` | `text` | | +| `eventType` | `text` (default `'screening'`) | `screening`, `watch_party`, `meetup`, `other` | +| `startTime` | `timestamptz` (NOT NULL) | | +| `endTime` | `timestamptz` | Optional, for duration | +| `timezone` | `text` (default `'America/New_York'`) | IANA timezone | +| `location` | `text` | e.g., "Discord Stage", "VR Chat", "Online" | +| `externalLink` | `text` | Link to event page, stream, etc. | +| `imageCdnKey` | `text` | Optional event image | +| `isPublished` | `boolean` (default false) | Draft mode | +| `isRecurring` | `boolean` (default false) | Placeholder for future recurring support | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** INDEX on `(siteId, startTime)`. INDEX on `(siteId, isPublished)`. + +**Recurring events:** V1 treats all events as one-off. The `isRecurring` flag is a placeholder. A future phase could add a `recurrenceRule` field (JSON or a separate table) for repeat patterns. Don't build recurring logic in V1. + +--- + +### `homepageSections` (Optional V1) + +If the homepage needs more structure than a single text block, sections allow ordered content blocks. + +| Column | Type | Notes | +|--------|------|-------| +| `id` | `uuid` (PK) | | +| `siteId` | `uuid` β†’ `sites.id` (NOT NULL) | | +| `type` | `text` (NOT NULL) | `hero`, `about`, `events`, `links`, `custom` | +| `title` | `text` | Section heading | +| `content` | `text` | Markdown or plain text | +| `settings` | `jsonb` | Section-specific config | +| `sortOrder` | `integer` (default 0) | | +| `isVisible` | `boolean` (default true) | | +| `createdAt` | `timestamptz` | | +| `updatedAt` | `timestamptz` | | + +**Indexes:** INDEX on `(siteId, sortOrder)`. + +**V1 recommendation:** Start without this table. Use the `homepage` JSON in `siteSettings` for the first version. Add sections in Phase 2+ if sites need more flexible page building. + +--- + +## Entity Relationship Summary + +```mermaid +erDiagram + sites ||--o{ memberships : "has" + sites ||--|| siteSettings : "has" + sites ||--o{ assets : "owns" + sites ||--o{ navLinks : "has" + sites ||--o{ socialLinks : "has" + sites ||--o{ events : "hosts" + users ||--o{ memberships : "has" + users ||--o{ assets : "uploads" + + sites { + uuid id PK + text slug UK + text name + boolean isActive + } + + users { + uuid id PK + text discordId UK + text discordUsername + text discordAvatar + } + + memberships { + uuid id PK + uuid siteId FK + uuid userId FK + enum role + } + + siteSettings { + uuid id PK + uuid siteId FK UK + jsonb settings + } + + events { + uuid id PK + uuid siteId FK + text title + timestamptz startTime + boolean isPublished + } +``` + +--- + +## Migration Strategy + +1. **All migrations run manually** β€” not on app startup. David runs `drizzle-kit migrate` locally or via a primary deployment. +2. **Additive changes only in production** β€” new columns, new tables. Avoid renames or destructive changes without a plan. +3. **JSON columns for settings** reduce migration frequency for feature additions. +4. **Seed data** β€” a seed script can populate the initial site record for a new deployment, or David creates the site row manually. + +## What This Schema Intentionally Avoids + +- **No `accounts` or `sessions` tables** β€” Better Auth manages those. +- **No `pages` table for V1** β€” homepage content lives in `siteSettings.homepage` JSON. +- **No `reviews`, `comments`, `posts` tables** β€” future phases. +- **No `featureFlags` table** β€” use env vars or settings JSON for now. +- **No `domains` table** β€” single `SITE_SLUG` resolution in V1. +- **No `auditLog` table** β€” nice to have later, not needed for V1. +- **No `invitations` table** β€” owner adds admins directly in V1, no invite flow. diff --git a/docs/03-feature-roadmap.md b/docs/03-feature-roadmap.md new file mode 100644 index 0000000..ac235f3 --- /dev/null +++ b/docs/03-feature-roadmap.md @@ -0,0 +1,163 @@ +# Feature Roadmap + +## How to Read This + +Each phase builds on the previous one. Phases are ordered by dependency, not by importance. + +**The rule:** Phase 1 must be complete and working before starting Phase 2. Later phases can be reordered based on need. + +--- + +## Phase 1: Foundation Minimum Viable Product + +**Goal:** A working SvelteKit app that resolves a site by `SITE_SLUG`, shows a public homepage, lets the owner log in and edit settings, and supports image uploads with CDN storage. + +### Deliverables + +- [ ] SvelteKit project initialized with TypeScript +- [ ] Drizzle ORM configured, connected to Postgres +- [ ] Core database tables created: `sites`, `users`, `memberships`, `siteSettings`, `assets` +- [ ] Better Auth integrated with Discord OAuth provider +- [ ] Site resolver: reads `SITE_SLUG`, loads site + settings from DB, attaches to `locals` +- [ ] Public homepage renders with site name and basic content +- [ ] Login page: "Login with Discord" button +- [ ] Owner bootstrap: `OWNER_DISCORD_ID` env var creates owner membership on first login +- [ ] Super admin bootstrap: `SUPER_ADMIN_DISCORD_IDS` env var grants cross-site access +- [ ] Admin auth guard: `/admin/*` routes redirect unauthenticated users to login +- [ ] Basic admin dashboard page (placeholder with site name) +- [ ] Admin settings page: edit site name and tagline (saved to `siteSettings` JSON) +- [ ] CDN storage integration (Bunny CDN or S3-compatible) +- [ ] Image upload endpoint with webp conversion and optimization +- [ ] File validation: accepted types, max size +- [ ] Asset records created in database on upload +- [ ] Asset library page in admin: browse, search, copy CDN URL +- [ ] Migration automation: primary deployment runs migrations on startup; others skip via `RUN_MIGRATIONS` env var + +### What's NOT in Phase 1 +- No branding customization (logo, colors) β€” Phase 2 +- No homepage content editing beyond name/tagline β€” Phase 2 +- No events, nav links, social links β€” Phase 2 / Phase 4 +- No role management UI β€” Phase 5 +- No super admin dashboard UI β€” Phase 5 + +--- + +## Phase 2: Branding & Customization + +**Goal:** Site owners can customize the look and feel of their site. The public site reflects branding settings. Asset upload is already available from Phase 1. + +### Deliverables + +- [ ] Admin branding page: select logo, background image, favicon from asset library +- [ ] Admin theme page: preset selector (dark/light/custom), accent color, background color, text color +- [ ] CSS custom properties generated from theme settings +- [ ] Admin homepage editor: hero title, subtitle, about text, CTA button text/link +- [ ] Public site renders all branding and homepage settings +- [ ] Admin nav links manager: add, edit, reorder, delete header/footer links +- [ ] Admin social links manager: add, edit, reorder, delete social platform links +- [ ] Public site renders nav links and social links +- [ ] Layout preset support (single configurable layout for V1) + +### What's NOT in Phase 2 +- Multiple layout options (just one flexible layout) +- Custom CSS fields +- Per-page theming +- Theme marketplace or sharing + +--- + +## Phase 3: Events & Schedule + +**Goal:** Sites can display upcoming events. Admins can manage events through the admin panel. + +### Deliverables + +- [ ] Events table created (if not already) +- [ ] Admin events manager: create, edit, delete, publish/unpublish events +- [ ] Event fields: title, description, type, start time, end time, timezone, location, external link, image +- [ ] Public homepage: "Next Event" card (shows the next upcoming published event) +- [ ] Public homepage: "Upcoming Events" list/schedule section +- [ ] Event detail page (optional β€” can be a modal or external link for V1) +- [ ] Timezone display handling (show event time in visitor's local time via JS) + +### What's NOT in Phase 3 +- Recurring/repeating events +- Calendar feed (iCal/RSS) +- Event reminders or notifications +- Attendee RSVPs +- Integration with Discord events + +--- + +## Phase 4: Super Admin Dashboard + +**Goal:** David (system maintainer) can manage all sites from a central dashboard. + +### Deliverables + +- [ ] Super admin auth: `SUPER_ADMIN_DISCORD_IDS` env var bypasses site-scoped membership checks +- [ ] Super admin dashboard: list all sites with status, quick links +- [ ] Create new site flow: insert site row, generate setup instructions +- [ ] View any site's settings, events, assets (read-only cross-site access) +- [ ] Feature flag management across sites +- [ ] Site deactivation/reactivation + +### What's NOT in Phase 4 +- Full site provisioning automation (still manual Coolify setup) +- Usage analytics or billing +- Impersonation (login as site owner) + +--- + +## Phase 5: Admin Improvements + +**Goal:** Better admin experience, role management, and operational tooling. + +### Deliverables + +- [ ] Role management: owner can add/remove admins and editors +- [ ] Admin list page showing all team members with roles +- [ ] Preview mode: admins can preview unpublished changes +- [ ] Improved admin dashboard with quick stats +- [ ] Site cloning helper (manual or scripted) for creating new sites +- [ ] Feature flags via settings JSON or env vars +- [ ] Audit-like log of who changed what (basic) +- [ ] Enhanced super admin dashboard: cross-site search, bulk operations + +### What's NOT in Phase 5 +- Full audit trail with rollback +- Granular permission system +- Multi-owner support per site + +--- + +## Phase 6: Future (Optional, Not Planned in Detail) + +These are ideas for later. Do not build any of these until Phases 1-5 are solid. + +- **Community features:** reviews, comments, discussion posts +- **Discord integration:** server widget, event sync, role sync +- **Calendar feeds:** iCal export, Google Calendar integration +- **AI tools:** content suggestions, event descriptions, semantic search (pgvector) +- **Advanced theming:** multiple layout presets, custom CSS per site +- **Analytics:** page views, event clicks, simple dashboard +- **Email notifications:** event reminders, new content alerts +- **Single-deployment model:** switch from multi-Coolify-deployment to one deployment resolving sites by domain +- **Public API:** read-only API for events and site info + +--- + +## Phase Dependency Diagram + +```mermaid +flowchart TD + P1[Phase 1: Foundation + Assets] --> P2[Phase 2: Branding & Customization] + P1 --> P3[Phase 3: Events & Schedule] + P2 --> P3 + P1 --> P4[Phase 4: Super Admin Dashboard] + P3 --> P5[Phase 5: Admin Improvements] + P4 --> P5 + P5 --> P6[Phase 6: Future Features] +``` + +**Note:** Phase 1 now includes CDN + asset upload (previously Phase 3). Phase 4 (Super Admin Dashboard) can start as soon as Phase 1 is done β€” it's independent of branding and events. Phase 5 enhances both regular admin and super admin experiences. diff --git a/docs/04-environment-variables.md b/docs/04-environment-variables.md new file mode 100644 index 0000000..159de19 --- /dev/null +++ b/docs/04-environment-variables.md @@ -0,0 +1,192 @@ +# Environment Variables Document β€” The Collective Hub + +## Overview + +Environment variables are the only difference between deployments. Each Coolify deployment has its own set of env vars, but all deployments share the same database, CDN, and Discord OAuth app. + +--- + +## Variable Reference + +### Required for Every Deployment + +| Variable | Example | Description | Shared or Per-Site? | +|----------|---------|-------------|---------------------| +| `SITE_SLUG` | `bad-movies-theater` | Identifies which site this deployment serves. Must match a `slug` in the `sites` table. | **Per-site** | +| `PUBLIC_SITE_URL` | `https://badmovies.example.com` | The public URL of this deployment. Used for auth callbacks, canonical URLs. | **Per-site** | +| `DATABASE_URL` | `postgresql://user:pass@host:5432/collective_hub` | Postgres connection string. | **Shared** (same for all) | +| `BETTER_AUTH_SECRET` | (generated) | Secret key for Better Auth session signing. | **Shared** (same for all) | +| `BETTER_AUTH_URL` | `https://badmovies.example.com` | Base URL for auth callbacks. Must match `PUBLIC_SITE_URL`. | **Per-site** | +| `DISCORD_CLIENT_ID` | `123456789012345678` | Discord OAuth application client ID. | **Shared** | +| `DISCORD_CLIENT_SECRET` | `abc123...` | Discord OAuth application client secret. | **Shared** | +| `OWNER_DISCORD_ID` | `123456789012345678` | Discord user ID of the site owner. Used to bootstrap ownership on first login. | **Per-site** | + +### Required for CDN (Phase 1) + +| Variable | Example | Description | Shared or Per-Site? | +|----------|---------|-------------|---------------------| +| `CDN_BASE_URL` | `https://cdn.example.com` | Base URL for constructing CDN URLs. | **Shared** | +| `CDN_STORAGE_ENDPOINT` | `https://ny.storage.bunnycdn.com` | Storage API endpoint. | **Shared** | +| `CDN_ACCESS_KEY` | `abc123...` | Storage access key. | **Shared** | +| `CDN_SECRET_KEY` | (S3 only) | Secret key for S3-compatible storage. | **Shared** | +| `CDN_BUCKET` | `collective-hub` | Bucket or storage zone name. | **Shared** | +| `CDN_REGION` | `us-east-1` | Region for S3-compatible storage. | **Shared** | + +### Super Admin + +| Variable | Example | Description | Shared or Per-Site? | +|----------|---------|-------------|---------------------| +| `SUPER_ADMIN_DISCORD_IDS` | `123456789,987654321` | Comma-separated Discord user IDs with cross-site super admin access. | **Shared** | + +### Migration Control + +| Variable | Example | Description | Shared or Per-Site? | +|----------|---------|-------------|---------------------| +| `RUN_MIGRATIONS` | `true` | Whether this deployment should run database migrations on startup. Only one deployment should have this set to `true`. | **Per-site** (only one `true`) | + +### Optional + +| Variable | Example | Description | Shared or Per-Site? | +|----------|---------|-------------|---------------------| +| `NODE_ENV` | `production` | Node environment. | **Per-site** (usually `production`) | +| `LOG_LEVEL` | `info` | Logging verbosity. | **Per-site** | +| `FEATURE_FLAGS` | `events:on` | Comma-separated feature flags (future). | **Per-site** | + +--- + +## Example: Full Deployment Env File + +### Deployment: bad-movies-theater (primary β€” runs migrations) + +```env +# Site Identity +SITE_SLUG=bad-movies-theater +PUBLIC_SITE_URL=https://badmovies.example.com + +# Database (shared) +DATABASE_URL=postgresql://hub_app:password@db.example.com:5432/collective_hub + +# Auth (Better Auth) +BETTER_AUTH_SECRET=generated-secret-value-here +BETTER_AUTH_URL=https://badmovies.example.com + +# Discord OAuth (shared) +DISCORD_CLIENT_ID=123456789012345678 +DISCORD_CLIENT_SECRET=your-discord-client-secret + +# Ownership Bootstrap +OWNER_DISCORD_ID=123456789012345678 + +# Super Admin +SUPER_ADMIN_DISCORD_IDS=111111111111111111 + +# Migration Control +RUN_MIGRATIONS=true + +# CDN (shared) +CDN_BASE_URL=https://cdn.example.com +CDN_STORAGE_ENDPOINT=https://ny.storage.bunnycdn.com +CDN_ACCESS_KEY=your-bunny-access-key +CDN_BUCKET=collective-hub + +# Optional +NODE_ENV=production +LOG_LEVEL=info +``` + +### Deployment: garbage-day (secondary β€” skips migrations) + +```env +# Site Identity +SITE_SLUG=garbage-day +PUBLIC_SITE_URL=https://garbageday.example.com + +# Database (shared β€” same value) +DATABASE_URL=postgresql://hub_app:password@db.example.com:5432/collective_hub + +# Auth (Better Auth) +BETTER_AUTH_SECRET=generated-secret-value-here +BETTER_AUTH_URL=https://garbageday.example.com + +# Discord OAuth (shared β€” same value) +DISCORD_CLIENT_ID=123456789012345678 +DISCORD_CLIENT_SECRET=your-discord-client-secret + +# Ownership Bootstrap +OWNER_DISCORD_ID=987654321098765432 + +# Super Admin (same value) +SUPER_ADMIN_DISCORD_IDS=111111111111111111 + +# Migration Control +RUN_MIGRATIONS=false + +# CDN (shared β€” same values) +CDN_BASE_URL=https://cdn.example.com +CDN_STORAGE_ENDPOINT=https://ny.storage.bunnycdn.com +CDN_ACCESS_KEY=your-bunny-access-key +CDN_BUCKET=collective-hub + +# Optional +NODE_ENV=production +LOG_LEVEL=info +``` + +--- + +## What's Shared vs Per-Site + +``` +Shared across ALL deployments: +β”œβ”€β”€ DATABASE_URL (one database) +β”œβ”€β”€ BETTER_AUTH_SECRET (same session signing key) +β”œβ”€β”€ DISCORD_CLIENT_ID (one Discord OAuth app) +β”œβ”€β”€ DISCORD_CLIENT_SECRET +β”œβ”€β”€ SUPER_ADMIN_DISCORD_IDS (system maintainers) +β”œβ”€β”€ CDN_BASE_URL (one CDN bucket) +β”œβ”€β”€ CDN_STORAGE_ENDPOINT +β”œβ”€β”€ CDN_ACCESS_KEY +β”œβ”€β”€ CDN_SECRET_KEY (if S3) +β”œβ”€β”€ CDN_BUCKET +└── CDN_REGION (if S3) + +Unique per deployment: +β”œβ”€β”€ SITE_SLUG (which site this is) +β”œβ”€β”€ PUBLIC_SITE_URL (its domain) +β”œβ”€β”€ BETTER_AUTH_URL (must match PUBLIC_SITE_URL) +β”œβ”€β”€ OWNER_DISCORD_ID (who owns this site) +└── RUN_MIGRATIONS (only one deployment = true) +``` + +--- + +## Notes & Warnings + +### Discord OAuth: Shared App + +All sites share one Discord OAuth application. This means: +- Users see the same app name when authorizing (e.g., "The Collective Hub") +- The OAuth redirect URL list must include every site's callback URL +- Discord has a limit on redirect URLs β€” manageable for a handful of sites +- If the system grows to many sites, each site may need its own Discord OAuth app, or a central auth domain pattern should be introduced + +### Better Auth Secret + +`BETTER_AUTH_SECRET` must be the same across all deployments because sessions are signed with it. This enables super admins to potentially navigate between site admin panels with a single session (future enhancement). + +### Database Migrations β€” Automated but Coordinated + +Migrations run automatically on app startup, but only on the deployment with `RUN_MIGRATIONS=true`. All other deployments skip migrations (`RUN_MIGRATIONS=false`). This means: + +- **Exactly one deployment** is designated as the migration runner +- That deployment must be deployed first when schema changes are made +- If the migration runner is down, other deployments still work (they just can't run new migrations) +- Choose a stable, low-traffic deployment as the migration runner (or the super admin dashboard deployment) + +### Super Admin Access + +`SUPER_ADMIN_DISCORD_IDS` is a comma-separated list of Discord user IDs. Users matching these IDs bypass site-scoped membership checks and can access any site's admin panel. This is intended for David (system maintainer) and should be kept to a minimal, trusted set of IDs. + +### Sensitive Values + +All secrets (database URL, auth secrets, Discord secrets, CDN keys) must be stored securely in Coolify's environment variable management β€” never committed to the repository. diff --git a/docs/05-admin-ux-plan.md b/docs/05-admin-ux-plan.md new file mode 100644 index 0000000..b3a8d2c --- /dev/null +++ b/docs/05-admin-ux-plan.md @@ -0,0 +1,265 @@ +# Admin UX Planning Document β€” The Collective Hub + +## Design Principles + +- **Practical over fancy.** A basic form that works beats a beautiful UI that's confusing. +- **One page per concern.** Settings, branding, homepage, links, events, assets β€” each gets its own admin page. +- **Instant feedback.** Save button with clear success/error state. No ambiguous "it might have saved" experiences. +- **Site-scoped by default, super admin cross-site.** Regular admins see only their site. Super admins (David) can access any site's admin panel. +- **Mobile-accessible but desktop-first.** Admins will primarily manage their site from a desktop/laptop. + +--- + +## Login Flow + +```mermaid +sequenceDiagram + participant A as Admin/Owner + participant S as Site + participant D as Discord + + A->>S: Clicks "Admin" or visits /admin + S->>S: Check session + S-->>A: Redirect to /login (if not logged in) + A->>S: Clicks "Login with Discord" + S->>D: Redirect to Discord OAuth + D->>A: Authorize screen + A->>D: Approve + D->>S: Callback with code + S->>S: Exchange code, get user info + S->>S: Check OWNER_DISCORD_ID match + S->>S: Create/confirm membership (owner role) + S->>S: Create session + S-->>A: Redirect to /admin +``` + +### Login Page + +A simple, centered page with: +- Site logo (or site name if no logo set) +- "Login with Discord" button (prominent, branded) +- Brief explanation: "Sign in to manage [Site Name]" +- No other login methods in V1 + +### First Owner Login + +1. Owner visits `/login` +2. Logs in with Discord +3. System detects their Discord ID matches `OWNER_DISCORD_ID` +4. Owner membership created automatically +5. Redirected to admin dashboard +6. Dashboard shows: "Welcome, [username]. You are the owner of [Site Name]." + +### Super Admin Login + +Super admins (Discord IDs listed in `SUPER_ADMIN_DISCORD_IDS`): +- Can log in to any site's admin panel regardless of `OWNER_DISCORD_ID` +- See a "Super Admin" badge or indicator in the admin UI +- Have a "View All Sites" link (placeholdered until Phase 4 super admin dashboard) +- Can perform all actions a site owner can + +### Non-Owner Login (Before Role Management) + +If a non-owner, non-super-admin logs in (Phase 1-4 before role management exists): +- They are authenticated but have no membership for the current site +- Show: "You don't have access to manage this site. Contact the site owner." +- No admin pages are accessible + +### Session Behavior + +- Session persists across browser restarts (HTTP-only cookie via Better Auth) +- Logout button in admin nav clears session +- Session expiry: Better Auth defaults (configurable) + +--- + +## Admin Layout + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ [Logo/Name] Admin Panel [User] [Logout] β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ β”‚ +β”‚ Dashboardβ”‚ β”‚ +β”‚ Settings β”‚ Content Area β”‚ +β”‚ Branding β”‚ β”‚ +β”‚ Homepage β”‚ β”‚ +β”‚ Links β”‚ β”‚ +β”‚ Events β”‚ β”‚ +β”‚ Assets β”‚ β”‚ +β”‚ Team β”‚ β”‚ +β”‚ β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +- **Left sidebar:** Navigation links. Highlight current page. Collapse on mobile (hamburger). +- **Top bar:** Site name, current user avatar + name, logout button. +- **Content area:** The active page content. + +--- + +## Admin Pages + +### Dashboard (`/admin`) + +**Purpose:** Quick overview and navigation hub. + +**Content:** +- Welcome message with owner name +- Site status: "Your site is live at [URL]" +- Quick stats (future): event count, page views +- Quick links to common actions: "Edit Homepage", "Manage Events" +- In V1, this can be minimalβ€”a simple landing page after login + +### Settings (`/admin/settings`) + +**Purpose:** Basic site identity. + +**Fields:** +- Site name (text input) +- Tagline (text input) +- Save button + +**Behavior:** +- Load current values from `siteSettings` JSON +- Save updates the JSON blob +- Success toast: "Settings saved" +- Error toast with specific message on failure + +### Branding (`/admin/branding`) + +**Purpose:** Visual identity and theme. + +**Fields:** +- Logo: file upload button OR manual URL input (Phase 2: asset picker from library) +- Background image: same pattern +- Favicon: file upload +- Theme preset: dropdown (Dark, Light, Custom) +- Accent color: color picker + hex input +- Background color: color picker + hex input +- Text color: color picker + hex input + +**Behavior:** +- Color pickers show live preview of the color +- "Preview" link opens public site in new tab +- Save updates `siteSettings.branding` and `siteSettings.theme` in JSON + +### Homepage (`/admin/homepage`) + +**Purpose:** Edit public homepage content. + +**Fields:** +- Hero title (text input) +- Hero subtitle (text input) +- About/intro text (textarea, plain text or basic Markdown) +- Primary button text (text input, e.g., "Join Discord") +- Primary button link (URL input) +- Toggle: Show next event section (checkbox) +- Toggle: Show schedule section (checkbox) + +**Behavior:** +- All fields are optional β€” empty fields are hidden on the public site +- Save updates `siteSettings.homepage` in JSON +- "View site" link opens public homepage in new tab + +### Links (`/admin/links`) + +**Purpose:** Manage navigation and social links. + +**Sub-pages or tabs:** +- **Nav Links tab:** Table of links with label, URL, position (header/footer), sort order +- **Social Links tab:** Table of links with platform (dropdown: Discord, Twitter/X, YouTube, Twitch, etc.), label, URL, sort order + +**Behavior:** +- Add new link: inline form at top or modal +- Edit: inline or modal +- Delete: with confirmation +- Drag-to-reorder (nice-to-have, manual sort order numbers are fine for V1) +- Save is per-link or "Save all changes" button + +### Events (`/admin/events`) + +**Purpose:** Manage event listings. + +**List view:** +- Table: title, date/time, status (published/draft), actions (edit/delete) +- "Add Event" button +- Filter: upcoming, past, drafts + +**Event edit/create form:** +- Title (text, required) +- Description (textarea) +- Event type (dropdown: Screening, Watch Party, Meetup, Other) +- Start time (datetime picker) +- End time (datetime picker, optional) +- Timezone (dropdown, defaults to `America/New_York`) +- Location (text, e.g., "Discord Stage") +- External link (URL) +- Event image (upload or URL) +- Published toggle + +**Behavior:** +- Events sorted by start time +- Draft events hidden from public site +- Delete with confirmation +- Basic validation: title required, start time required + +### Assets (`/admin/assets`) + +**Purpose:** Browse and manage uploaded files. + +**List view:** +- Grid or table of assets with thumbnail, filename, type, size, date +- Search/filter by filename +- Click to copy CDN URL +- Delete with confirmation + +**Upload:** +- Drag-and-drop zone or file input +- Accept: image/webp, image/png, image/jpeg +- Max size: configurable (e.g., 5MB) +- Progress indicator during upload +- Success: asset appears in list + +**Note:** Asset upload with webp conversion is available from Phase 1. The asset library is fully functional from day one β€” no manual URL phase. + +### Team (`/admin/team`) β€” Phase 5+ + +**Purpose:** Manage admins and editors. + +**List view:** +- Table: user avatar, username, role, actions (change role, remove) + +**Add member:** +- Input for Discord username or ID +- Role dropdown +- "Add" button + +**Behavior:** +- Owner cannot be removed or demoted +- Owner can promote/demote/remove admins and editors +- Changes take effect immediately + +--- + +## Error States & Edge Cases + +| Situation | Behavior | +|-----------|----------| +| Save fails (network error) | Show error toast, keep form data intact | +| Save fails (validation) | Highlight invalid fields, show specific messages | +| Session expires while editing | Redirect to login on next action, preserve intended destination | +| Concurrent editing (two admins) | Last write wins in V1 (no conflict detection) | +| Loading state | Skeleton/spinner while data loads | +| Empty state | "No events yet. Create your first event!" with action button | +| CDN unreachable | Admin still works; image uploads fail with clear error | + +--- + +## What to Avoid + +- **Multi-step wizards.** Single-page forms are simpler. +- **Inline editing everywhere.** Form pages with clear save buttons are more predictable. +- **Real-time preview in V1.** A "preview" link to the public site is sufficient. +- **Over-designed dashboards.** The admin panel is a tool, not a product demo. +- **Custom permission UIs in V1.** Owner + super admin access is sufficient until Phase 5. diff --git a/docs/06-public-site-ux-plan.md b/docs/06-public-site-ux-plan.md new file mode 100644 index 0000000..7387a7b --- /dev/null +++ b/docs/06-public-site-ux-plan.md @@ -0,0 +1,202 @@ +# Public Site UX Planning Document + +## Design Principles + +- **Simple landing page, not a full website.** The public site is a single page (with maybe an event detail modal or page). It tells visitors who the community is, what they do, when they meet, and how to join. +- **Content-driven by settings.** Everything on the page comes from the database (site settings, events, links). No hardcoded content. +- **Theme-aware.** The page renders with the site's branding settings: logo, colors, background image. +- **Fast and accessible.** Server-side rendered, minimal client JS, semantic HTML. +- **Mobile-responsive.** Many visitors will check on their phones. + +--- + +## Homepage Layout + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ NAV BAR β”‚ +β”‚ [Logo] Site Name [Link1] [Link2] [Link3] β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ HERO SECTION β”‚ +β”‚ [Background Image Optional] β”‚ +β”‚ β”‚ +β”‚ Site Name (large heading) β”‚ +β”‚ Tagline / Subtitle β”‚ +β”‚ [Primary CTA Button] β”‚ +β”‚ β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ ABOUT / INTRO SECTION β”‚ +β”‚ β”‚ +β”‚ About text (from settings) β”‚ +β”‚ β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ NEXT EVENT SECTION β”‚ +β”‚ (if showNextEvent is enabled) β”‚ +β”‚ β”‚ +β”‚ "Next Event" heading β”‚ +β”‚ Event card with: β”‚ +β”‚ - Title β”‚ +β”‚ - Date/Time β”‚ +β”‚ - Description snippet β”‚ +β”‚ - [Event Link / Details] β”‚ +β”‚ β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ UPCOMING SCHEDULE SECTION β”‚ +β”‚ (if showSchedule is enabled) β”‚ +β”‚ β”‚ +β”‚ "Upcoming Events" heading β”‚ +β”‚ List of upcoming events: β”‚ +β”‚ - Date | Title | Type β”‚ +β”‚ - Each links to event or external β”‚ +β”‚ β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ β”‚ +β”‚ SOCIAL LINKS SECTION β”‚ +β”‚ β”‚ +β”‚ [Discord] [Twitter] [YouTube] ... β”‚ +β”‚ Icon + label, opens in new tab β”‚ +β”‚ β”‚ +β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ +β”‚ FOOTER β”‚ +β”‚ Footer nav links β”‚ +β”‚ "Powered by The Collective Hub" β”‚ +β”‚ Copyright / site name β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +--- + +## Section Details + +### Nav Bar + +- **Position:** Sticky top (optional, can be static) +- **Content:** + - Site logo (or site name text if no logo) + - Site name (hidden if logo is present and preferred) + - Nav links from database (header position), ordered by `sortOrder` +- **Mobile:** Hamburger menu collapses nav links into a drawer or dropdown +- **Behavior:** External links open in new tab with `rel="noopener noreferrer"` + +### Hero Section + +- **Background:** Site background image (if set) with overlay/gradient for text readability. Falls back to background color. +- **Content:** + - Site name (large heading, `h1`) + - Tagline/subtitle (`p` or `h2`) + - Primary CTA button (if button text and link are set) +- **Button styling:** Uses accent color. Links to Discord invite, event page, or any URL set by admin. +- **If no hero content is set:** Section collapses or shows a minimal version with just the site name. + +### About / Intro Section + +- **Content:** About text from settings. Plain text or basic Markdown rendered to HTML. +- **If empty:** Section is hidden entirely. +- **Styling:** Clean typography, max-width for readability (~65ch). + +### Next Event Section + +- **Visibility:** Only shown if `showNextEvent` is enabled AND at least one published event exists with a future `startTime`. +- **Content:** A single event card showing the soonest upcoming event. + - Event title + - Date and time (displayed in visitor's local timezone via client-side JS) + - Short description (truncated) + - Event type badge/chip + - Location (if set) + - Link: "Event Details" β†’ external link or internal event page +- **If no upcoming events:** Optionally show "No upcoming events β€” check back soon!" or hide section. + +### Upcoming Schedule Section + +- **Visibility:** Only shown if `showSchedule` is enabled. +- **Content:** List of upcoming published events (excluding the one shown in "Next Event" if duplicate). +- **List format:** + - Date (short format) + - Event title + - Event type icon or badge + - Optional: time, location +- **Max items:** Configurable, e.g., show next 5 events with a "View all events" link if more exist. +- **If no events:** Hide the section. + +### Social Links Section + +- **Visibility:** Shown if any social links exist in the database. +- **Content:** Row of icon+label links for each social platform. +- **Icons:** Simple SVG icons or icon font. Recognizable platform icons (Discord, Twitter/X, YouTube, Twitch, GitHub, etc.). +- **Behavior:** All open in new tab. + +### Footer + +- **Content:** + - Footer-position nav links (if any) + - Optional: "Powered by The Collective Hub" credit + - Site name / copyright +- **Styling:** Subtle, smaller text, subdued colors. + +--- + +## Theme Rendering + +The site's theme settings are applied via CSS custom properties on the root element: + +```css +:root { + --color-accent: #e63946; + --color-background: #1a1a2e; + --color-text: #eaeaea; + --color-text-secondary: #b0b0b0; + --font-family: 'Inter', sans-serif; + /* derived values generated from presets if needed */ +} +``` + +**Theme Presets:** +- **Dark:** Dark background, light text, accent color applied +- **Light:** Light background, dark text, accent color applied +- **Custom:** Owner sets each color manually + +Presets provide sensible defaults for derived colors (card backgrounds, borders, muted text) so the owner only needs to pick 3 colors. + +--- + +## States + +| State | Behavior | +|-------|----------| +| **Loading** | Server-rendered, so no loading spinner on initial load. Fast. | +| **Empty site (no settings)** | Show site name from `sites` table. Everything else gracefully hidden. | +| **No events** | Hide event sections. | +| **No branding set** | Use neutral default colors (dark theme as fallback). | +| **Error (data fetch fails)** | Show a minimal page with site name. Log error server-side. Don't crash. | +| **Site deactivated** (`isActive=false`) | Show a simple "Site is currently unavailable" page with HTTP 503. | + +--- + +## Responsive Behavior + +- **Desktop (β‰₯1024px):** Full layout as designed. Multi-column where appropriate. +- **Tablet (768-1023px):** Same layout, adjusted spacing. Nav may collapse. +- **Mobile (<768px):** Single column. Hamburger nav. Stacked sections. Larger touch targets for buttons. + +--- + +## Performance Targets + +- Server-rendered HTML (SSR) β€” no client-side rendering for public pages +- Minimal JavaScript β€” only for timezone conversion, mobile nav toggle +- Images from CDN with proper `width`/`height` and `loading="lazy"` on below-fold images +- No client-side data fetching for public pages (all data loaded server-side) + +--- + +## What to Avoid + +- **Animation-heavy designs.** Subtle transitions are fine; scroll-triggered animations are not needed. +- **Over-complicated layouts.** One column of stacked sections works well and is easy to maintain. +- **Custom fonts that hurt performance.** System font stack or a single web font (Inter) is sufficient. +- **Client-side routing for public pages.** The homepage is one page. If event detail pages are added later, they should be server-rendered too. +- **Assuming content exists.** Every section must handle the "nothing configured yet" case gracefully. diff --git a/docs/07-development-plan.md b/docs/07-development-plan.md new file mode 100644 index 0000000..ec97e17 --- /dev/null +++ b/docs/07-development-plan.md @@ -0,0 +1,260 @@ +# Development Implementation Plan + +## How to Use This + +This is a step-by-step build order for Phase 1 and beyond. Each step lists what to build, what it depends on, and how to verify it works. + +**Follow the order.** Each step builds on the previous one. Don't skip ahead. + +--- + +## Phase 1: Foundation + +### Step 1: Initialize SvelteKit Project + +**What to do:** +- Create a new SvelteKit project with `create-svelte` (choose TypeScript, ESLint, Prettier) +- Set up the directory structure as outlined in the architecture plan +- Configure `svelte.config.js` with the Node adapter for production builds +- Create a basic `+page.svelte` that says "Hello World" +- Create a `Dockerfile` for production builds + +**Depends on:** Nothing. + +**Verify:** `npm run dev` starts. Browser shows "Hello World". `docker build` succeeds. + +--- + +### Step 2: Set Up Postgres and Drizzle + +**What to do:** +- Install `drizzle-orm`, `drizzle-kit`, and `postgres` (the npm package) +- Create `drizzle.config.ts` +- Create `src/lib/server/db/index.ts` with the Postgres connection +- Create `src/lib/server/db/schema.ts` with the `sites` table only (start simple) +- Run `drizzle-kit push` to create the table in Postgres +- Insert a test site row manually: `INSERT INTO sites (slug, name) VALUES ('test-site', 'Test Site');` + +**Depends on:** Step 1. A running Postgres instance (local Docker or remote). + +**Verify:** `drizzle-kit studio` shows the table. A simple script can query the test site. + +--- + +### Step 3: Create Core Tables + +**What to do:** +- Add all Phase 1 tables to `schema.ts`: `sites`, `users`, `memberships`, `siteSettings` +- Define types, enums, indexes, and foreign keys +- Run `drizzle-kit push` to create all tables +- Optionally create a seed script for a test site + +**Depends on:** Step 2. + +**Verify:** All tables exist in the database. Relationships are correct in Drizzle Studio. + +--- + +### Step 4: Implement Site Resolver + +**What to do:** +- Create `src/lib/server/site-resolver.ts` +- Export a function `getSiteBySlug(slug: string)` that queries the `sites` table and includes `siteSettings` +- In `src/hooks.server.ts`, read `SITE_SLUG` from env, call the resolver, attach site to `locals` +- Augment `app.d.ts` so `locals.site` is typed +- In `src/routes/+layout.server.ts`, load site data from locals and return it +- The homepage `+page.svelte` should display the site name + +**Depends on:** Step 3. + +**Verify:** Set `SITE_SLUG=test-site` in `.env`. Homepage shows "Test Site". Change the slug, restart, page breaks cleanly. + +--- + +### Step 5: Set Up Better Auth with Discord + +**What to do:** +- Install Better Auth and follow its SvelteKit setup guide +- Configure Discord OAuth provider +- Create `src/lib/server/auth.ts` with the Better Auth configuration +- Add the Better Auth API route: `src/routes/api/auth/[...betterAuth]/+server.ts` +- Create a `/login` page with a "Login with Discord" button +- On successful login, upsert the user into the `users` table + +**Depends on:** Step 3 (users table must exist). + +**Verify:** Visit `/login`, click the Discord button, authorize, get redirected back. User record appears in the `users` table. + +--- + +### Step 6: Implement Owner Bootstrap + +**What to do:** +- In the auth callback or post-login hook, check if `user.discordId === process.env.OWNER_DISCORD_ID` +- If match: upsert a membership row with role `owner` for the current site +- In `src/hooks.server.ts`, after auth, load the user's membership for the current site and attach to `locals` +- Create an admin auth guard: a `+layout.server.ts` in `/admin` that checks `locals.membership` + +**Depends on:** Step 4 (site resolver), Step 5 (auth). + +**Verify:** Log in with the Discord account matching `OWNER_DISCORD_ID`. Membership row with `owner` role appears. Navigate to `/admin` β€” accessible. Log in with a different Discord account β€” `/admin` redirects to `/login` with an error message. + +--- + +### Step 7: Build Admin Layout + +**What to do:** +- Create `src/routes/admin/+layout.svelte` with sidebar navigation and top bar +- Create `src/routes/admin/+layout.server.ts` with the auth guard +- Create a minimal `src/routes/admin/+page.svelte` dashboard + +**Depends on:** Step 6. + +**Verify:** Owner logs in, sees admin layout with nav sidebar. Non-owner cannot access. + +--- + +### Step 8: Build Admin Settings Page + +**What to do:** +- Create `src/routes/admin/settings/+page.svelte` +- Form fields: site name, tagline +- Load current values from `siteSettings.settings` JSON +- Create a form action (or API endpoint) that updates the JSON +- Add basic form validation and success/error feedback + +**Depends on:** Step 7. + +**Verify:** Owner can edit site name and tagline. Changes persist after reload. Public homepage reflects changes. + +--- + +### Step 9: Build Public Homepage + +**What to do:** +- Update `src/routes/+page.server.ts` to load site settings as a flat object +- Build `src/routes/+page.svelte` with sections: + - Hero (site name, tagline, CTA button if configured) + - About (text from settings if configured) +- Apply basic CSS styling with CSS custom properties (hardcode dark theme defaults for now) +- Handle empty states: sections hide when no content configured + +**Depends on:** Step 4 (site resolver), Step 8 (settings exist). + +**Verify:** Public homepage shows site name and content. Changing settings in admin updates the public page. + +--- + +### Step 10: Add Theme CSS Variables + +**What to do:** +- In the root layout, generate CSS custom properties from theme settings +- Fall back to sensible defaults if no theme configured +- Apply variables to the public homepage +- Admin panel can use a fixed theme (don't need the public theme in admin) + +**Depends on:** Step 9. + +**Verify:** Changing accent color in admin (once branding page is built) changes the public page's button color. Default theme looks clean. + +--- + +### Step 11: Set Up CDN and Asset Upload + +**What to do:** +- Configure CDN storage client (Bunny CDN or S3-compatible) +- Create `src/lib/server/cdn.ts` with upload, delete, and URL construction helpers +- Create an image upload API endpoint: `src/routes/api/assets/+server.ts` +- Implement webp conversion and optimization (using `sharp` or similar) +- File validation: accepted types (PNG, JPEG, WebP input), max size +- Auto-generate CDN keys: `sites/{siteSlug}/{type}/{uuid}.webp` +- Create asset records in the `assets` table on successful upload +- Create asset library page: `src/routes/admin/assets/+page.svelte` + +**Depends on:** Step 4 (site resolver for siteSlug), Step 7 (admin layout). + +**Verify:** Upload an image via admin. Asset record appears in database. File exists in CDN bucket. Asset library page shows uploaded files. Image is served correctly via CDN URL. + +--- + +### Step 12: Set Up Migration Automation + +**What to do:** +- Add `RUN_MIGRATIONS` env var check in app startup +- If `RUN_MIGRATIONS=true`, run `drizzle-kit migrate` on startup +- If `RUN_MIGRATIONS=false` (or unset), skip migrations entirely +- Log migration status on startup for observability +- Document which deployment is the migration runner + +**Depends on:** Step 2 (Drizzle configured). + +**Verify:** Start app with `RUN_MIGRATIONS=true` β€” migrations run. Start with `RUN_MIGRATIONS=false` β€” migrations are skipped. Both deployments work against the same database. + +--- + +### Step 13: Implement Super Admin Access + +**What to do:** +- Parse `SUPER_ADMIN_DISCORD_IDS` env var (comma-separated) on startup +- In the auth hook / membership check, compare user's Discord ID against the super admin list +- If match: bypass site-scoped membership checks, grant full admin access +- Attach super admin flag to `locals` for conditional UI (e.g., "View All Sites" link) + +**Depends on:** Step 6 (owner bootstrap / membership logic). + +**Verify:** Log in with a Discord ID in `SUPER_ADMIN_DISCORD_IDS`. Access any site's admin panel. Log in with a non-super-admin ID β€” restricted to their own site. + +--- + +### Step 14: Admin Branding Page + +**What to do:** +- Create `src/routes/admin/branding/+page.svelte` +- Color pickers for accent, background, text colors +- Theme preset dropdown (Dark, Light, Custom) +- Logo and background selectors: pick from asset library (uploaded in Step 11) + +**Depends on:** Step 8 (settings save pattern), Step 11 (asset library). + +**Verify:** Owner can change colors. Public page reflects changes immediately. Logo and background can be selected from uploaded assets. + +--- + +### Step 15: Dockerize and Deploy + +**What to do:** +- Finalize Dockerfile (multi-stage build for Node) +- Create `docker-compose.yml` for local testing with Postgres +- Set up first Coolify deployment (designate as migration runner: `RUN_MIGRATIONS=true`) +- Configure all environment variables in Coolify +- Deploy and verify public site is accessible + +**Depends on:** Step 9 (working public site), Step 12 (migration automation). + +**Verify:** Site is live at the configured URL. Login works. Admin works. Migrations ran on startup. + +--- + +## Phase 2 Onward + +Once Phase 1 is fully working, continue with: + +1. Nav links + social links admin pages and public rendering +2. Homepage content editor (hero title, subtitle, about text, CTA) +3. Events: schema, admin CRUD, public render +4. Super admin dashboard (Phase 4) +5. Role management (Phase 5) + +Detailed steps for Phases 2-5 should be written once Phase 1 is complete and any lessons learned are incorporated. + +--- + +## Development Rules + +- **One migration per schema change.** Don't batch unrelated changes into one migration. +- **Test with multiple SITE_SLUG values locally.** Use different `.env` files or a script that switches them. +- **Commit often.** Small, focused commits are easier to reason about. +- **Migrations run automatically on startup, gated by `RUN_MIGRATIONS`.** Only one deployment runs them. All others skip. +- **Keep the public site SSR-only.** No client-side data fetching for public pages. +- **Admin pages can use client-side interactivity.** Forms, file uploads, etc. can use Svelte's client-side features. +- **All uploaded images are converted to webp.** No raw user files stored on CDN. diff --git a/docs/08-open-questions.md b/docs/08-open-questions.md new file mode 100644 index 0000000..152ba1f --- /dev/null +++ b/docs/08-open-questions.md @@ -0,0 +1,87 @@ +# Decision Register β€” The Collective Hub + +All key architectural and product decisions made during planning. This document serves as the authoritative record of what was decided and why. + +--- + +## Auth & Discord + +| # | Decision | Rationale | +|---|----------|-----------| +| Q1 | **One shared Discord OAuth app** for all sites in V1 | Simpler to manage. Works for up to ~10 sites before Discord's redirect URL limit becomes an issue. Each site's callback URL is added to the Discord app's redirect list. Switch to per-site apps later if needed. | +| Q2 | **Defer central auth domain** | Not needed for V1. Architecture supports adding it later. | + +## Sites & Domains + +| # | Decision | Rationale | +|---|----------|-----------| +| Q3 | **Support both custom domains and subdomains** | The app doesn't care what the URL is β€” it uses `PUBLIC_SITE_URL` from env vars. DNS and Coolify routing are manual per site. Each site runs in its own Coolify container. | +| Q4 | **No Host header validation in V1** | Each site is in its own container. Trust the `SITE_SLUG` env var. Add Host validation if moving to single-deployment multi-domain later. | + +## Roles & Permissions + +| # | Decision | Rationale | +|---|----------|-----------| +| Q5 | **Defer admin invites to Phase 5** | V1 has one owner per site bootstrapped via `OWNER_DISCORD_ID`. David has cross-site access via `SUPER_ADMIN_DISCORD_IDS`. The `memberships` table supports multiple members from day one β€” just no UI for it yet. | +| Q6 | **Multi-site membership with different roles** | Already baked into the schema. A user can be owner of one site and editor of another. No special handling needed. | + +## Super Admin + +| # | Decision | Rationale | +|---|----------|-----------| +| β€” | **`SUPER_ADMIN_DISCORD_IDS` env var** for cross-site super admin access | Comma-separated Discord user IDs. David (system maintainer) can access any site's admin panel. These IDs bypass site-scoped membership checks. A dedicated super admin dashboard is planned for Phase 4. | + +## Content & Customization + +| # | Decision | Rationale | +|---|----------|-----------| +| Q7 | **Single `jsonb` column for theme/site settings** | Simpler than separate columns or key-value tables. No migrations needed when adding new settings. Settings are always loaded as a batch β€” no need to query individual settings in SQL. | +| Q8 | **Fixed homepage fields for V1** | Hero title, about text, CTA button, etc. stored in settings JSON. Covers 90% of what theater sites need. A flexible `homepageSections` table is defined in the database plan as a future upgrade. | +| Q9 | **Basic Markdown for long text fields** | About text and event descriptions support headings, bold, italic, links, lists. No raw HTML passthrough for safety. Short fields (hero title, button text) are plain text only. | +| Q10 | **Customization checklist confirmed as drafted** | Name/tagline/logo/colors/hero/CTA/nav/social/theme presets in V1. No custom CSS, no extra layout presets, no custom fonts, no custom pages beyond homepage. | + +### V1 Customization Scope (Q10 Detail) + +| Feature | V1? | Phase | +|---------|-----|-------| +| Site name, tagline | βœ… Yes | Phase 1 | +| Logo, background image | βœ… Yes | Phase 2 (from asset library) | +| Accent/background/text colors | βœ… Yes | Phase 2 | +| Hero title, subtitle, about text | βœ… Yes | Phase 2 | +| CTA button text and link | βœ… Yes | Phase 2 | +| Nav links | βœ… Yes | Phase 2 | +| Social links | βœ… Yes | Phase 2 | +| Theme presets (dark/light) | βœ… Yes | Phase 2 | +| Custom CSS | ❌ No | Future | +| Multiple layout presets | ❌ No | One flexible layout | +| Custom fonts | ❌ No | System stack + Inter | +| Per-page customization | ❌ No | Homepage only | +| Custom pages beyond homepage | ❌ No | Future | + +## Events + +| # | Decision | Rationale | +|---|----------|-----------| +| Q11 | **No recurring events in V1** | V1 events are one-off. The `isRecurring` boolean is a placeholder. Recurring events add significant complexity (RRULE parsing, occurrence generation, timezone math). | +| Q12 | **UTC storage + client-side timezone conversion** | All event times stored as `timestamptz` in UTC. Event's intended timezone stored as a string. Public site converts to visitor's local time using `Intl.DateTimeFormat`. | + +## Assets & CDN + +| # | Decision | Rationale | +|---|----------|-----------| +| Q13 | **Full upload flow from day one** | No manual URL pasting. Admin uploads images through the app. Assets table tracks all files. CDN integration is Phase 1, not deferred. | +| Q14 | **Auto webp conversion and optimization on upload** | All uploaded images are converted to webp and optimized before storage. Uses `sharp` or similar for processing. Consistent format, smaller files, better performance. | + +## Database & Operations + +| # | Decision | Rationale | +|---|----------|-----------| +| Q15 | **Automated migrations, gated by `RUN_MIGRATIONS` env var** | Exactly one deployment (the "primary") has `RUN_MIGRATIONS=true` and runs migrations on startup. All others skip. This avoids migration collisions while eliminating manual steps. | +| Q16 | **Backups handled externally by David** | Not a code concern. David manages Postgres backups separately. | +| β€” | **Shared database with `siteId` scoping** | Confirmed after discussion. One Postgres database, all tables scoped by `siteId`. Simpler than per-site tables/schemas/databases. Enables super admin cross-site queries. | + +## Project Identity + +| # | Decision | Rationale | +|---|----------|-----------| +| Q17 | **Project name: The Collective Hub** | Chosen by David. Used for repo name, package name, documentation references, CDN bucket name, database name, and public references (e.g., Discord OAuth app name). | diff --git a/docs/09-risks-and-rules.md b/docs/09-risks-and-rules.md new file mode 100644 index 0000000..bd87e76 --- /dev/null +++ b/docs/09-risks-and-rules.md @@ -0,0 +1,152 @@ +# Risks & Things to Avoid + +## Critical Risks + +### Risk 1: Multiple Deployments Running Migrations Simultaneously + +**Severity:** High β€” could corrupt the database. + +**Why it's a risk:** With multiple Coolify deployments all pointing to the same database, if every deployment runs migrations on startup, they could conflict β€” two containers trying to create the same table at the same time. + +**Mitigation:** +- Migrations run automatically on startup, but gated by `RUN_MIGRATIONS` env var +- **Exactly one deployment** has `RUN_MIGRATIONS=true` (the "primary" deployment) +- All other deployments set `RUN_MIGRATIONS=false` and skip migrations +- Deploy the primary first when schema changes are included +- This is enforced by convention, not by a lock β€” David must ensure only one deployment has the flag set to `true` + +### Risk 2: Missing siteId Scope on Queries + +**Severity:** High β€” data leaks between sites. + +**Why it's a risk:** If a query forgets to filter by `siteId`, one site could display another site's events, settings, or assets. This is the most common multi-tenant bug. + +**Mitigation:** +- All data access functions accept `siteId` as a required parameter +- Create a helper that wraps Drizzle queries and enforces `siteId` +- Review every query in code review for `siteId` filtering +- Consider a lint rule or type-level enforcement (e.g., branded types) later + +### Risk 3: Hardcoding Full CDN URLs + +**Severity:** Medium β€” painful CDN migration if the CDN provider changes. + +**Why it's a risk:** If the database stores `https://cdn.example.com/sites/bad-movies/logo.webp` and you later switch CDN providers, every URL in the database needs updating. + +**Mitigation:** +- Database stores only the CDN key/path (`sites/bad-movies-theater/logo.webp`) +- Application constructs full URLs using `CDN_BASE_URL` env var +- A single env var change switches all CDN URLs + +### Risk 4: Overbuilding Before the Core Works + +**Severity:** Medium β€” wasted effort, complexity without value. + +**Why it's a risk:** It's tempting to build the fancy admin dashboard, the AI features, the perfect theming system before the basic site actually works end-to-end. This leads to a complex codebase that doesn't ship. + +**Mitigation:** +- Follow the phases strictly +- Phase 1 must be fully working (public site + admin login + settings save) before anything else +- A working simple site is infinitely more valuable than a half-built complex one +- Ask "Can this wait until Phase X?" before building anything + +### Risk 5: Per-Site Custom Code + +**Severity:** Medium β€” maintenance nightmare. + +**Why it's a risk:** If "Bad Movies Theater" needs something special and you add an `if (site.slug === 'bad-movies-theater')` in the code, that's the start of a slippery slope. Soon every site has special cases, and the "shared codebase" advantage is lost. + +**Mitigation:** +- Never write site-specific conditional logic +- All customization comes from the database (settings, theme, content) +- If a site genuinely needs a unique feature, it should be built as a configurable feature for all sites, or that site should fork the codebase (last resort) + +### Risk 6: Letting Site Owners Write Raw CSS/HTML + +**Severity:** Medium β€” security and maintenance risk. + +**Why it's a risk:** Allowing custom CSS or HTML opens XSS vectors (if not properly sanitized), breaks the design system, and makes future template updates unpredictable. A site owner could accidentally break their own site's layout. + +**Mitigation:** +- No custom CSS field in V1 +- No raw HTML in content fields β€” use Markdown with safe rendering +- If custom CSS is ever added (future phase), sandbox it (e.g., a per-site stylesheet loaded separately, not injected into the main app) +- Clearly document that custom CSS is an advanced/risky feature + +--- + +## Design Pitfalls to Avoid + +### Pitfall 1: Making the Admin Panel Too Complex Before the Public Page Works + +The admin panel exists to serve the public page. If you spend weeks on a beautiful admin UI but the public site is a broken placeholder, priorities are wrong. + +**Rule:** The public page must work before any admin page is considered complete. + +### Pitfall 2: Building AI Features Before the Core Template Works + +AI content suggestions, semantic search with pgvector, AI chatbots β€” these are exciting but useless if a site can't display a homepage with basic content. + +**Rule:** No AI features until Phase 5+ and even then, only if the core template is stable and useful. + +### Pitfall 3: Planning Too Many Layout Options + +One clean, flexible layout that adapts to content is better than three half-baked layout options. Adding a second layout doubles the testing surface. + +**Rule:** One layout in V1. Add a second only when there's a clear, proven need. + +### Pitfall 4: Normalizing Settings Too Aggressively + +A `siteSettings` table with 30 columns (one per setting) means a migration for every new setting. A `jsonb` column means adding a setting is zero-cost. + +**Rule:** Settings go in JSON. Structured, relational data (events, links, assets) goes in normalized tables. + +### Pitfall 5: Building for Scale That Doesn't Exist Yet + +Planning for 1,000 sites when you have 3 leads to over-engineering. The architecture supports growth (multi-tenant from day one), but don't optimize for scale prematurely. + +**Rule:** Architecture should not block growth; implementation should not optimize for it yet. + +--- + +## Process Risks + +### Risk 7: Skipping Documentation + +**Severity:** Low now, high later. + +**Why it's a risk:** When there's only one developer (David), documentation feels optional. But when you come back to the project after 6 months, or when a site owner asks how something works, missing documentation hurts. + +**Mitigation:** +- These planning docs live in the repo +- Add a simple `README.md` with setup instructions +- Add code comments for non-obvious logic +- Keep a `CHANGELOG.md` once the project is live + +### Risk 8: Super Admin Account Compromise + +**Severity:** High β€” cross-site data breach. + +**Why it's a risk:** A `SUPER_ADMIN_DISCORD_IDS` entry grants unrestricted access to all sites. If a super admin's Discord account is compromised, all sites are exposed. + +**Mitigation:** +- Keep the super admin list minimal (ideally just David) +- Super admin Discord accounts should have 2FA enabled +- Consider adding a secondary verification step for super admin actions in a future phase +- Monitor for unusual super admin activity + +--- + +## Summary Checklist + +Before writing any code, confirm: + +- [ ] Migrations are automated but gated by `RUN_MIGRATIONS` β€” only one deployment runs them +- [ ] Every query includes `siteId` filtering +- [ ] CDN keys stored in DB, not full URLs +- [ ] Phase 1 scope is locked β€” no feature creep +- [ ] No site-specific conditional code planned +- [ ] No raw CSS/HTML inputs for site owners +- [ ] Database backups are configured (handled externally by David) +- [ ] Project name decided: **The Collective Hub** +- [ ] Super admin Discord IDs are set and accounts have 2FA enabled