If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/basecamp/fizzy shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4d ago
• 10 active contributors
• Distributed ownership (top contributor 23% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live basecamp/fizzy repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/basecamp/fizzy.

What it runs against: a local clone of basecamp/fizzy — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in basecamp/fizzy | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 34 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of basecamp/fizzy. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/basecamp/fizzy.git
#   cd fizzy
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of basecamp/fizzy and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "basecamp/fizzy(\\.git)?\\b" \\
  && ok "origin remote is basecamp/fizzy" \\
  || miss "origin remote is not basecamp/fizzy (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f ".claude/CLAUDE.md" \\
  && ok ".claude/CLAUDE.md" \\
  || miss "missing critical file: .claude/CLAUDE.md"
test -f "app/assets/images" \\
  && ok "app/assets/images" \\
  || miss "missing critical file: app/assets/images"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 34 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~4d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/basecamp/fizzy"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Fizzy is a Kanban board application built by 37signals that reimagines issue and idea tracking through a columnar Kanban interface. It's a Ruby on Rails monolith (1.3M+ LOC) with HTML/CSS/JavaScript frontends that lets teams visualize and manage work as cards moving across customizable workflow states, marketed as 'Kanban as it should be' rather than bolted-on to existing tools. Classic Rails monolith: app/ contains controllers, models, views, and assets (.svg icons); Dockerfile enables containerized deployment; dual Gemfile setup (OSS vs SaaS) suggests runtime configuration branches. Uses .mise.toml for local dev environment management and GitHub Actions for CI/CD across three distinct pipelines (OSS, SaaS, publish-image).

Teams and organizations (especially those using 37signals products like Basecamp) who want a dedicated, purpose-built Kanban board for issue tracking and ideation without the bloat of general-purpose project management tools. Both self-hosted operators (via Docker/Kamal) and Fizzy SaaS users.

Production-ready and actively maintained. The codebase is substantial (1.3M Ruby lines), has both OSS and SaaS CI pipelines (.github/workflows/ci-checks.yml, ci-saas.yml, test.yml), and includes Docker deployment infrastructure (Dockerfile, Dockerignore, kamal/dockerfile deployment docs). This is a live commercial product with dual deployment models (managed SaaS + self-hosted).

Low risk for active use, but medium complexity for customization: the project maintains separate Gemfiles (Gemfile and Gemfile.saas) suggesting diverging dependency paths between OSS and SaaS versions, which could cause merge conflicts or version skew. The O'Saasy license is non-standard and may restrict commercial redistribution. Self-hosted operators depend on 37signals staying responsive to issues; no visible issue backlog metrics in provided data.

Active development with recent CI pipeline refinements: .github/workflows includes test.yml, dependabot-sync-saas-lockfile.yml (indicating ongoing SaaS/OSS sync challenges), and publish-image.yml. CONTRIBUTING.md and STYLE.md suggest ongoing community engagement. No specific PR/milestone data visible, but gitleaks.toml and dependabot.yml indicate security and dependency vigilance.

Clone and set up for development: git clone https://github.com/basecamp/fizzy.git && cd fizzy && bundle install && rails db:setup. Check docs/development.md for full dev environment details. For Docker deployment reference docs/docker-deployment.md; for Kamal deployment reference docs/kamal-deployment.md.

Daily commands: Development: rails s (after bundle install). Production Docker: docker build -t fizzy . && docker run fizzy with environment config (see Dockerfile). See docs/development.md for full local setup; docs/docker-deployment.md for containerized deployments.

• Gemfile — Defines all Ruby dependencies and gem versions; required to understand project structure and capabilities.
• .claude/CLAUDE.md — Project guidelines and conventions specific to this codebase that all contributors must follow.
• app/assets/images — Core asset directory containing UI icons and branding elements used throughout the Kanban interface.
• Dockerfile — Defines containerization strategy and runtime environment for production deployments.
• README.md — Entry point documentation explaining Fizzy's purpose, deployment options, and contribution process.
• .rubocop.yml — Code style and linting rules that enforce consistency across Ruby contributions.
• CONTRIBUTING.md — Contribution guidelines and process that all contributors must understand before submitting code.

• Rails Controllers (Rails, ActiveRecord) — Route HTTP requests, load data from database, render board views and handle card operations
  • Failure mode: Invalid card updates, missing data in board render, 500 errors on controller logic failure
• Kanban Service Layer (Ruby) — Business logic for organizing cards into columns, applying filters, sorting, and validating state transitions
  • Failure mode: Incorrect card ordering, filter logic bugs, cards appearing in multiple columns or none
• Database Layer (PostgreSQL/MySQL, ActiveRecord migrations) — Persists boards, cards, columns, user assignments, and audit trails; enforces data integrity
  • Failure mode: Data loss, orphaned records, referential integrity violations, slow queries on large datasets
• Frontend UI (HTML/ERB, CSS, JavaScript, SVG icons) — Renders Kanban board layout, handles drag-and-drop interactions, displays real-time updates via WebSocket
  • Failure mode: Broken layout on mobile, drag-drop failures, UI not updating on server changes, missing icons
• Docker Container (Docker, Linux base image) — Encapsulates application, runtime, and dependencies for consistent deployment across environments
  • Failure mode: Image won't start, missing environment variables, port conflicts, volume mount failures

• User → Rails Router — HTTP request to load board or update card (GET /boards/:id, PATCH /cards/:id)
• Rails Router → Controller — Route matches and dispatches request to appropriate action
• Controller → Database — Query cards, columns, filters using ActiveRecord (SELECT, UPDATE queries)
• Database → Kanban Service — Raw card and column records returned for processing and organization
• Kanban Service → Cache Layer — Formatted board state stored with TTL for faster subsequent reads
• Kanban Service → View Renderer — Processed board data passed to ERB template for HTML generation
• View Renderer → Browser — HTML, CSS, JavaScript,

Add a new UI icon or image asset

1. Create or export your icon as an SVG file (app/assets/images/[icon-name].svg)
2. Use the icon in views via Rails asset pipeline (app/views/[view-name].html.erb)
3. Run linter to ensure code quality (.rubocop.yml)

Deploy a custom Fizzy instance

1. Review deployment options documented in README (README.md)
2. For Docker deployment, customize the Dockerfile if needed (Dockerfile)
3. Set up environment variables and configuration (.env.example (inferred))
4. Deploy using Docker or Kamal based on flexibility needs (docs/docker-deployment.md (referenced in README))

Contribute code changes

1. Review contribution guidelines and expected workflow (CONTRIBUTING.md)
2. Follow code style and conventions (STYLE.md)
3. Ensure code passes linting and style checks (.rubocop.yml)
4. Submit pull request and wait for CI/CD validation (.github/workflows/ci-checks.yml)

• Ruby on Rails — Provides rapid development, convention-over-configuration for Kanban feature delivery, and mature ORM for database operations.
• Docker — Enables consistent deployment across development, staging, and production environments; simplifies self-hosted and cloud deployments.
• SVG assets — Scalable vector graphics for UI icons ensure crisp rendering on all screen sizes and provide lightweight asset payloads.
• GitHub Actions — Automates testing, linting, and deployment pipelines; integrates natively with repository for seamless CI/CD.

• Single codebase for self-hosted and SaaS deployments

  • Why: Reduces maintenance burden and keeps feature parity between versions.
  • Consequence: Requires careful conditional logic (Gemfile.saas) to handle SaaS-specific dependencies; may introduce complexity.

• Docker-first deployment strategy

  • Why: Simplifies onboarding for self-hosted users and eliminates 'works on my machine' issues.
  • Consequence: Requires Docker knowledge from operators; adds container overhead compared to bare-metal deployment.

• Kanban-only feature focus

  • Why: Allows deep optimization and polished UX for issue/idea tracking without feature bloat.
  • Consequence: Not a general-purpose project management tool; may not suit teams needing Gantt charts or other views.

• Multi-project management with complex hierarchy (focused on flat Kanban boards)
• Real-time synchronization at sub-second latency (uses polling/WebSocket with reasonable TTLs)
• Built-in authentication layer (delegates to external identity providers or basic HTTP auth)
• Offline-first or local-only operation (requires backend connectivity)

Dual Gemfile management: bundle install defaults to Gemfile; must explicitly use --gemfile=Gemfile.saas for SaaS variant or CI will fail. The dependabot-sync-saas-lockfile workflow suggests OSS and SaaS lock files can drift; always run both bundle commands locally. O'Saasy License restrictions may apply to forks/modifications — review LICENSE.md before redistributing. Mise is required for consistent Ruby version (check .mise.toml and .ruby-version); using wrong Ruby version may cause silent test failures.

• Kanban Board State Machine — Core to Fizzy: cards move through discrete workflow columns (To Do → In Progress → Done, etc.), and the state transitions define allowed moves and visibility rules that shape the entire UI and business logic.
• Server-Rendered Hotwire (Turbo + Stimulus) — Modern Rails pattern for progressive enhancement; Fizzy likely uses Turbo to re-render board views on card moves without full page reloads, and Stimulus to bind JavaScript to card drag-drop events.
• Gemfile Variants / Multi-Config Package Management — Fizzy maintains Gemfile and Gemfile.saas in parallel; understanding how bundler resolves different lock files and how CI must test both variants is crucial to avoid breaking either deployment model.
• Monolithic Rails Architecture with Docker Scaling — Fizzy is a single Rails app, not a microservice; scaling and deployment rely on containerization (Dockerfile) and orchestration (Kamal), not service decomposition—this shapes how you modify and deploy changes.
• O'Saasy License (Non-Standard FOSS License) — Unlike GPL or MIT, O'Saasy restricts commercial use of forks; before forking Fizzy for commercial redistribution, you must understand and accept this license's limitations.
• CI/CD Pipeline Matrix Testing (OSS vs SaaS) — Fizzy's .github/workflows run separate test suites for OSS (ci-oss.yml) and SaaS (ci-saas.yml), with a dependabot sync job to keep them aligned. Understanding why these diverge prevents breaking either variant.

• jaredreich/pipefy — Alternative visual Kanban board tool in JavaScript; represents competitive solution in same problem space
• wekan/wekan — Open-source Kanban board (built on Meteor); closest mature OSS alternative for self-hosted Kanban
• rails/rails — Fizzy is a Rails monolith; understanding Rails internals (routing, AR, views) is essential to modifying Fizzy
• basecamp/basecamp — Sibling 37signals product; Fizzy integrates with or runs alongside Basecamp in many deployments
• basecamp/kamal — 37signals' own deployment tool; referenced in Fizzy's deployment docs and used for self-hosted rollouts

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for Kanban board state management

The repo has multiple CI workflows (ci-checks.yml, ci-oss.yml, test.yml) but the file structure shows app/assets with many SVG icons and likely controller/model logic without visible corresponding test files. Kanban boards have complex state transitions (card movement, column updates, filtering). Adding unit tests for core board operations would catch regressions early and help new contributors understand the state management model.

• [ ] Create test/models/board_test.rb for Board model operations (create, update, delete columns)
• [ ] Create test/models/card_test.rb for Card state transitions (status changes, assignments, filtering)
• [ ] Create test/controllers/boards_controller_test.rb for HTTP endpoints and authorization
• [ ] Add tests for drag-and-drop card movements between columns
• [ ] Run existing test.yml workflow to verify test suite integration

Document the filtering and search architecture referenced in assets

The file structure includes filter.svg and funnel.svg assets, suggesting filtering is a core feature, but the README snippet cuts off at 'Development guide'. There's a CONTRIBUTING.md, STYLE.md, and AGENTS.md but no specific technical documentation for how filters work, performance considerations, or API contracts. This is critical for OSS contributors wanting to extend filtering.

• [ ] Create docs/filtering-architecture.md explaining filter types (status, assignee, tags, dates) and data flow
• [ ] Document the GraphQL/REST API endpoints for filter queries with examples
• [ ] Add performance considerations for large boards with many filters applied
• [ ] Reference relevant controller/model files that implement filtering logic
• [ ] Link from CONTRIBUTING.md to this new documentation

Add missing GitHub Actions workflow for security scanning and dependency updates

The repo has .gitleaks.toml and .gitleaksignore files indicating secrets scanning concerns, plus .github/workflows/dependabot.yml for dependency management. However, there's no visible workflow for automated security scanning (SAST), vulnerability audits, or lock file validation across multiple Gemfiles (Gemfile, Gemfile.saas). Adding a security workflow would protect the OSS project and set expectations for contributors.

• [ ] Create .github/workflows/security.yml to run Bundler audit on both Gemfile and Gemfile.saas
• [ ] Add Brakeman static analysis for Rails security vulnerabilities
• [ ] Configure gitleaks scanning in CI to catch leaked credentials before merge
• [ ] Add dependency lock file validation to ensure Gemfile.lock and Gemfile.saas.lock are in sync
• [ ] Ensure workflow runs on pull_request and schedule weekly checks

• Expand SVG icon library: app/assets/images/ has 50+ icons but is missing common Kanban actions (e.g., 'archive.svg', 'duplicate.svg', 'link.svg'). Add 3–5 missing icons following the existing monochrome style and commit with style guide reference.: Low risk, high visibility; no model or controller changes needed, pure UI assets. Perfect for learning the repo structure.
• Write RSpec tests for the Kanban card state transition logic. The codebase has substantial Ruby LOC but test coverage for board movement/filtering is unclear. Add specs under spec/models/ or spec/controllers/ for the core card lifecycle.: Improves maintainability and reveals critical board logic; needed as codebase is large and OSS/SaaS split increases regression risk.
• Document the Gemfile.saas divergence: add a clear section to CONTRIBUTING.md explaining why there are two Gemfiles, when to use each, and how to sync them safely. Include the commands for running tests against both variants locally.: Prevents contributor confusion and reduces CI failures from wrong dependency variant; acknowledged gap in current contributor guide.

• High · Incomplete Docker Environment Configuration — Dockerfile (line with ENV RAILS_ENV). The Dockerfile shows a truncated environment variable setup (RAILS_ENV="pro is incomplete). This could lead to the container running in an undefined state or with incorrect security settings. The production environment configuration is critical for disabling debug modes and enabling security features. Fix: Complete the Dockerfile environment configuration. Ensure RAILS_ENV is set to 'production' and all required Rails security settings are properly configured (RAILS_LOG_TO_STDOUT, SECRET_KEY_BASE handling, etc.).
• High · Master Key Management in Docker — Dockerfile (documentation comments). The Dockerfile documentation mentions passing RAILS_MASTER_KEY via environment variable at runtime. While this is better than hardcoding, it exposes the master key in container inspection and logs. This key is used to decrypt the encrypted credentials file and should be handled with extreme care. Fix: Use Docker secrets management (Docker Swarm) or orchestration platform secrets (Kubernetes). Never pass sensitive keys as environment variables in production. Consider using external key management services (AWS Secrets Manager, HashiCorp Vault).
• Medium · Missing Security Headers Configuration — Rails application configuration (not visible in snippet). No visible configuration for security headers (CSP, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security) in the provided file structure. A Kanban application handling potentially sensitive project data should have comprehensive security headers. Fix: Configure security headers in Rails middleware or web server. Implement Content Security Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, and Strict-Transport-Security headers.
• Medium · Potential Dependency Vulnerabilities - Missing Dependency Analysis — Gemfile, Gemfile.lock, Gemfile.saas, Gemfile.saas.lock. While Gemfile and Gemfile.lock are referenced, their contents are not provided. Rails applications with outdated gems can introduce security vulnerabilities (especially in authentication, authorization, and SQL/XSS prevention). Fix: Run 'bundle audit' regularly to check for known vulnerabilities. Keep all dependencies updated, particularly security-critical gems like devise, pundit, rails-html-sanitizer, and activerecord. Implement dependency scanning in CI/CD pipeline.
• Medium · SQLite in Production Environment — Dockerfile (sqlite3 package installation). The Dockerfile installs sqlite3 package, suggesting SQLite may be used in production. SQLite is not suitable for production multi-user applications due to concurrency limitations and lack of proper database security features. Fix: Use PostgreSQL or MySQL for production deployments. SQLite should only be used for development/testing. Update database configuration to use a production-grade database with proper authentication, encryption, and access controls.
• Medium · Leaks Configuration File Present — .gitleaks.toml, .gitleaksignore. The presence of .gitleaks.toml and .gitleaksignore files indicates gitleaks is configured. While this is positive, the .gitleaksignore file could be used to suppress legitimate secret detection, potentially hiding credential leaks. Fix: Review .gitleaksignore to ensure it's not suppressing legitimate secret warnings. Never ignore actual secrets in the codebase. Use proper secrets management instead of storing credentials in git (even if ignored by gitleaks).
• Low · Docker Image Build Considerations — Dockerfile. The Dockerfile uses 'slim' variant of Ruby image which is good for reducing attack surface. However, no explicit security scanning or image hardening steps are visible (no explicit USER instruction to drop root privileges was shown in the truncated Dockerfile). Fix: Ensure the Dockerfile includes: a non-root USER instruction, explicit vulnerability scanning in CI/CD pipeline, minimal final stage if using multi-stage builds, and read-only filesystem where possible.
• Low · Missing CONTRIBUTING Security Guidance — CONTRIBUTING.md (content not provided). While CONTRIBUTING.md exists, there's no indication it covers security vulnerability reporting procedures. Open source projects should have clear security.md or security reporting guidelines. Fix: Create a SECURITY.md file with guidelines for responsible disclosure of security vulnerabilities. Include contact information for security reports and expected response times.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.