153 lines
6.9 KiB
Markdown
153 lines
6.9 KiB
Markdown
# 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
|