Jeremy Daer
a02042b4c5
* AGENTS.md: add Deploy section (main, 7 destinations, saas:enable) Structured format for agent prelude discovery and cross-app drift checking via verify-app-registry. * Address review: document beta template env var requirement The beta deploy config requires BETA_NUMBER; typical targets are beta1-beta4.
167 lines
5.6 KiB
Markdown
167 lines
5.6 KiB
Markdown
# Fizzy
|
|
|
|
This file provides guidance to AI coding agents working with this repository.
|
|
|
|
## What is Fizzy?
|
|
|
|
Fizzy is a collaborative project management and issue tracking application built by 37signals/Basecamp. It's a kanban-style tool for teams to create and manage cards (tasks/issues) across boards, organize work into columns representing workflow stages, and collaborate via comments, mentions, and assignments.
|
|
|
|
## Development Commands
|
|
|
|
### Setup and Server
|
|
```bash
|
|
bin/setup # Initial setup (installs gems, creates DB, loads schema)
|
|
bin/dev # Start development server (runs on port 3006)
|
|
```
|
|
|
|
Development URL: http://fizzy.localhost:3006
|
|
Login with: david@example.com (development fixtures), password will appear in the browser console
|
|
|
|
### Testing
|
|
```bash
|
|
bin/rails test # Run unit tests (fast)
|
|
bin/rails test test/path/file_test.rb # Run single test file
|
|
bin/rails test:system # Run system tests (Capybara + Selenium)
|
|
bin/ci # Run full CI suite (style, security, tests)
|
|
|
|
# For parallel test execution issues, use:
|
|
PARALLEL_WORKERS=1 bin/rails test
|
|
```
|
|
|
|
CI pipeline (`bin/ci`) runs:
|
|
1. Rubocop (style)
|
|
2. Bundler audit (gem security)
|
|
3. Importmap audit
|
|
4. Brakeman (security scan)
|
|
5. Application tests
|
|
6. System tests
|
|
|
|
### Database
|
|
```bash
|
|
bin/rails db:fixtures:load # Load fixture data
|
|
bin/rails db:migrate # Run migrations
|
|
bin/rails db:reset # Drop, create, and load schema
|
|
```
|
|
|
|
### Other Utilities
|
|
```bash
|
|
bin/rails dev:email # Toggle letter_opener for email preview
|
|
bin/jobs # Manage Solid Queue jobs
|
|
bin/kamal deploy # Deploy (requires 1Password CLI for secrets)
|
|
```
|
|
|
|
## Deploy
|
|
|
|
Default branch: `main`
|
|
Pre-deploy: `bin/rails saas:enable`
|
|
Deploy: `bin/kamal deploy -d <destination>`
|
|
Destinations: production, staging, beta, beta1, beta2, beta3, beta4
|
|
Note: `beta` is a template requiring `BETA_NUMBER` env var; typical targets are `beta1`-`beta4`.
|
|
|
|
## Architecture Overview
|
|
|
|
### Multi-Tenancy (URL-Based)
|
|
|
|
Fizzy uses **URL path-based multi-tenancy**:
|
|
- Each Account (tenant) has a unique `external_account_id` (7+ digits)
|
|
- URLs are prefixed: `/{account_id}/boards/...`
|
|
- Middleware (`AccountSlug::Extractor`) extracts the account ID from the URL and sets `Current.account`
|
|
- The slug is moved from `PATH_INFO` to `SCRIPT_NAME`, making Rails think it's "mounted" at that path
|
|
- All models include `account_id` for data isolation
|
|
- Background jobs automatically serialize and restore account context
|
|
|
|
**Key insight**: This architecture allows multi-tenancy without subdomains or separate databases, making local development and testing simpler.
|
|
|
|
### Authentication & Authorization
|
|
|
|
**Passwordless magic link authentication**:
|
|
- Global `Identity` (email-based) can have `Users` in multiple Accounts
|
|
- Users belong to an Account and have roles: owner, admin, member, system
|
|
- Sessions managed via signed cookies
|
|
- Board-level access control via `Access` records
|
|
|
|
### Core Domain Models
|
|
|
|
**Account** → The tenant/organization
|
|
- Has users, boards, cards, tags, webhooks
|
|
- Has entropy configuration for auto-postponement
|
|
|
|
**Identity** → Global user (email)
|
|
- Can have Users in multiple Accounts
|
|
- Session management tied to Identity
|
|
|
|
**User** → Account membership
|
|
- Belongs to Account and Identity
|
|
- Has role (owner/admin/member/system)
|
|
- Board access via explicit `Access` records
|
|
|
|
**Board** → Primary organizational unit
|
|
- Has columns for workflow stages
|
|
- Can be "all access" or selective
|
|
- Can be published publicly with shareable key
|
|
|
|
**Card** → Main work item (task/issue)
|
|
- Sequential number within each Account
|
|
- Rich text description and attachments
|
|
- Lifecycle: triage → columns → closed/not_now
|
|
- Automatically postpones after inactivity ("entropy")
|
|
|
|
**Event** → Records all significant actions
|
|
- Polymorphic association to changed object
|
|
- Drives activity timeline, notifications, webhooks
|
|
- Has JSON `particulars` for action-specific data
|
|
|
|
### Entropy System
|
|
|
|
Cards automatically "postpone" (move to "not now") after inactivity:
|
|
- Account-level default entropy period
|
|
- Board-level entropy override
|
|
- Prevents endless todo lists from accumulating
|
|
- Configurable via Account/Board settings
|
|
|
|
### UUID Primary Keys
|
|
|
|
All tables use UUIDs (UUIDv7 format, base36-encoded as 25-char strings):
|
|
- Custom fixture UUID generation maintains deterministic ordering for tests
|
|
- Fixtures are always "older" than runtime records
|
|
- `.first`/`.last` work correctly in tests
|
|
|
|
### Background Jobs (Solid Queue)
|
|
|
|
Database-backed job queue (no Redis):
|
|
- Custom `FizzyActiveJobExtensions` prepended to ActiveJob
|
|
- Jobs automatically capture/restore `Current.account`
|
|
- Mission Control::Jobs for monitoring
|
|
|
|
Key recurring tasks (via `config/recurring.yml`):
|
|
- Deliver bundled notifications (every 30 min)
|
|
- Auto-postpone stale cards (hourly)
|
|
- Cleanup jobs for expired links, deliveries
|
|
|
|
### Sharded Full-Text Search
|
|
|
|
16-shard MySQL full-text search instead of Elasticsearch:
|
|
- Shards determined by account ID hash (CRC32)
|
|
- Search records denormalized for performance
|
|
- Models in `app/models/search/`
|
|
|
|
### Imports and exports
|
|
|
|
Allow people to move between OSS and SAAS Fizzy instances:
|
|
- Exports/Imports can be written to/read from local or S3 storage depending on the config of the instance (both must be supported)
|
|
- Must be able to handle very large ZIP files (500+GB)
|
|
- Models in `app/models/account/data_transfer/`, `app/models/zip_file`
|
|
|
|
## Tools
|
|
|
|
### Chrome MCP (Local Dev)
|
|
|
|
URL: `http://fizzy.localhost:3006`
|
|
Login: david@example.com (passwordless magic link auth - check rails console for link)
|
|
|
|
Use Chrome MCP tools to interact with the running dev app for UI testing and debugging.
|
|
|
|
## Coding style
|
|
|
|
@STYLE.md
|