ldraney/westside-docs
1
0
Fork 0
Code Issues 1 Pull requests 1 Projects Releases Packages Wiki Activity Actions

Scaffold westside-docs: static docs app with Mermaid #2

Open
forgejo_admin wants to merge 3 commits from 1-scaffold-westside-docs into main
pull from: 1-scaffold-westside-docs
merge into: ldraney:main
Conversation 1 Commits 3 Files changed 86 +2874 -1
forgejo_admin commented 2026-05-10 16:10:00 +00:00
First-time contributor
Copy link

Summary

  • Strip ActiveRecord, solid_cache/queue/cable — this is a database-free docs site
  • Add DocsController with wildcard routing for ERB doc pages
  • Create architecture page (system overview, client dashboard, deployment, user roles diagrams)
  • Create user stories page (Marcus + parent flows)
  • Add plain CSS layout with navbar and Mermaid.js for diagrams
  • Migrate User Roles diagram from westside-ror draft docs (marked needs-review)

Closes #1

Test plan

  • Verify app boots without database: rails s with no PG connection
  • Visit /docs — index page renders with links
  • Visit /docs/architecture — all Mermaid diagrams render
  • Visit /docs/user-stories — user flow diagram renders
  • Visit /docs/nonexistent — returns 404
  • Verify deployed at westside-docs.tail5b443a.ts.net

🤖 Generated with Claude Code

## Summary - Strip ActiveRecord, solid_cache/queue/cable — this is a database-free docs site - Add DocsController with wildcard routing for ERB doc pages - Create architecture page (system overview, client dashboard, deployment, user roles diagrams) - Create user stories page (Marcus + parent flows) - Add plain CSS layout with navbar and Mermaid.js for diagrams - Migrate User Roles diagram from westside-ror draft docs (marked needs-review) Closes #1 ## Test plan - [ ] Verify app boots without database: `rails s` with no PG connection - [ ] Visit `/docs` — index page renders with links - [ ] Visit `/docs/architecture` — all Mermaid diagrams render - [ ] Visit `/docs/user-stories` — user flow diagram renders - [ ] Visit `/docs/nonexistent` — returns 404 - [ ] Verify deployed at westside-docs.tail5b443a.ts.net 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Fresh Rails 8.1 app for Westside Basketball documentation.
No Tailwind — plain CSS following ror-css-guide conventions.
Includes docs controller, architecture and user-stories pages,
Mermaid.js for diagrams.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
No database needed — removed ActiveRecord, active_storage, solid_*
gems. Cleared host authorization for dev. Updated README with live
URLs and stack overview.

Deployment fixes: libyaml-dev for psych gem, PID cleanup on startup,
startup probe with 5min tolerance, /docs probe path, 1Gi memory.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add User Roles diagram from westside-ror draft docs
Some checks failed
CI / scan_ruby (pull_request) Has been cancelled
Details
CI / scan_js (pull_request) Has been cancelled
Details
CI / lint (pull_request) Has been cancelled
Details
CI / test (pull_request) Has been cancelled
Details
CI / system-test (pull_request) Has been cancelled
Details
5bac3f17a4 
Migrated unique content (User Roles flowchart) from the old
westside-ror docs scaffold. Marked as needs-review.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
forgejo_admin commented 2026-05-10 16:15:02 +00:00
Author
First-time contributor
Copy link

PR #2 Review

Blockers

B1. Docker entrypoint will crash in production
bin/docker-entrypoint runs db:prepare unconditionally before starting the server. ActiveRecord is not loaded. The Dockerized app will crash on startup. Remove the database step from the entrypoint.

B2. Database-free cleanup incomplete
PR says "strip ActiveRecord" but several references remain:

  • gem "pg" still in Gemfile
  • config/database.yml still has full PostgreSQL config including production cache/queue/cable databases
  • config/cable.yml references Redis
  • CI workflow (.github/workflows/ci.yml) spins up PostgreSQL and runs db:test:prepare
  • test/test_helper.rb calls parallelize and fixtures :all (ActiveRecord deps)
  • app/jobs/application_job.rb references ActiveRecord::Deadlocked

Should Fix

  • No controller tests. Zero tests for the core functionality (wildcard routing, 404 handling). At minimum: GET /docs, /docs/architecture, /docs/user-stories return 200; GET /docs/nonexistent returns 404.
  • Kamal/Thruster still present. Gemfile includes both, config/deploy.yml has Kamal config with placeholder IP. Deployment is via k3s hostPath, not Kamal.
  • image_processing gem included. Active Storage dependency with no use case.
  • Generator boilerplate. Mailer infra, db/seeds.rb, config/storage.yml, GitHub Actions CI — none apply to a static docs site on Forgejo/k3s.

Nits

  • Mermaid CDN pinned to major version only (@11). Consider pinning specific version + SRI hash.
  • CSS declares Atkinson Hyperlegible font but no import exists — silent fallback to system-ui.
  • Index page uses hardcoded paths instead of docs_page_path route helpers.
  • Navbar missing aria-label for accessibility.
  • CSP initializer commented out despite CDN script tag.

SOP Compliance

  • Branch named after issue
  • PR body has Summary + Test Plan + Closes #1
  • PR body missing ## Related section (no plan slug)
  • Tests exist and pass
  • No unnecessary file changes (generator boilerplate)

VERDICT: REQUEST_CHANGES

Two blockers (entrypoint crash, incomplete AR removal) and missing tests. The docs content itself (architecture diagrams, user stories, Mermaid integration) is solid.

## PR #2 Review ### Blockers **B1. Docker entrypoint will crash in production** `bin/docker-entrypoint` runs `db:prepare` unconditionally before starting the server. ActiveRecord is not loaded. The Dockerized app will crash on startup. Remove the database step from the entrypoint. **B2. Database-free cleanup incomplete** PR says "strip ActiveRecord" but several references remain: - `gem "pg"` still in Gemfile - `config/database.yml` still has full PostgreSQL config including production cache/queue/cable databases - `config/cable.yml` references Redis - CI workflow (`.github/workflows/ci.yml`) spins up PostgreSQL and runs `db:test:prepare` - `test/test_helper.rb` calls `parallelize` and `fixtures :all` (ActiveRecord deps) - `app/jobs/application_job.rb` references `ActiveRecord::Deadlocked` ### Should Fix - **No controller tests.** Zero tests for the core functionality (wildcard routing, 404 handling). At minimum: GET /docs, /docs/architecture, /docs/user-stories return 200; GET /docs/nonexistent returns 404. - **Kamal/Thruster still present.** Gemfile includes both, `config/deploy.yml` has Kamal config with placeholder IP. Deployment is via k3s hostPath, not Kamal. - **`image_processing` gem included.** Active Storage dependency with no use case. - **Generator boilerplate.** Mailer infra, `db/seeds.rb`, `config/storage.yml`, GitHub Actions CI — none apply to a static docs site on Forgejo/k3s. ### Nits - Mermaid CDN pinned to major version only (`@11`). Consider pinning specific version + SRI hash. - CSS declares `Atkinson Hyperlegible` font but no import exists — silent fallback to system-ui. - Index page uses hardcoded paths instead of `docs_page_path` route helpers. - Navbar missing `aria-label` for accessibility. - CSP initializer commented out despite CDN script tag. ### SOP Compliance - [x] Branch named after issue - [x] PR body has Summary + Test Plan + Closes #1 - [ ] PR body missing `## Related` section (no plan slug) - [ ] Tests exist and pass - [ ] No unnecessary file changes (generator boilerplate) ### VERDICT: REQUEST_CHANGES Two blockers (entrypoint crash, incomplete AR removal) and missing tests. The docs content itself (architecture diagrams, user stories, Mermaid integration) is solid.
Some checks failed
CI / scan_ruby (pull_request) Has been cancelled
Details
CI / scan_js (pull_request) Has been cancelled
Details
CI / lint (pull_request) Has been cancelled
Details
CI / test (pull_request) Has been cancelled
Details
CI / system-test (pull_request) Has been cancelled
Details
This pull request can be merged automatically.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin 1-scaffold-westside-docs:1-scaffold-westside-docs
git switch 1-scaffold-westside-docs

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff 1-scaffold-westside-docs
git switch 1-scaffold-westside-docs
git rebase main
git switch main
git merge --ff-only 1-scaffold-westside-docs
git switch 1-scaffold-westside-docs
git rebase main
git switch main
git merge --no-ff 1-scaffold-westside-docs
git switch main
git merge --squash 1-scaffold-westside-docs
git switch main
git merge --ff-only 1-scaffold-westside-docs
git switch main
git merge 1-scaffold-westside-docs
git push origin main
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
ldraney/westside-docs!2
No description provided.