# moriw0/tyakudon architecture

> Architecture diagram of the GitHub repository moriw0/tyakudon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/moriw0/tyakudon
- Repository: https://github.com/moriw0/tyakudon

## Overview

1. **Overall shape**
   - This is a single Rails 7.1 monolith on Ruby 3.3, backed by PostgreSQL.
   - The app is server-rendered first, with Hotwire (Turbo + Stimulus) for progressive interactivity rather than a separate frontend service.

2. **Core product domain**
   - The main business flow is “ramen queue measurement”: users start a wait-time session, record the line/queue state, and finish when the ramen is served.
   - The central models for this are `User`, `RamenShop`, `Record`, and `LineStatus`, with `Record` representing the measured wait time and `LineStatus` representing the live queue state.

3. **Measurement flow**
   - `NewRecordsController` and `RecordsController` appear to orchestrate the measurement lifecycle: create/start, capture intermediate form input, show result, and present record detail pages.
   - Turbo Stream templates in `records/` and `line_statuses/` indicate that parts of this flow update in-place without full page reloads.

4. **Live queue/status layer**
   - `LineStatusesController` is a separate live-facing subsystem for posting current waiting conditions, likely used by people currently at a shop.
   - This layer is also interactive via Turbo Stream, and the related views suggest a queue table/edit form experience centered on the current state of a shop.

5. **Ramen shop directory and discovery**
   - `RamenShopsController` powers shop pages, search, nearby-shop lookup, maps, and favorites.
   - `db/migrate` plus `geocoder` config and JS map/geolocation controllers show that location is an important data dimension, not just a text attribute.

6. **Social/engagement features**
   - `Favorites` and `Likes` are separate relational features around shops and records.
   - These are updated through dedicated controllers with Turbo Stream responses, so user reactions immediately update the UI.
   - `CheerMessage` and its job suggest a lightweight “encouragement” layer around the waiting experience.

7. **User/account subsystem**
   - Authentication is handled in-app with sessions, password resets, account activations, and OmniAuth-based social login.
   - `users` includes admin/test-mode flags and provider/uid columns, so the user model is the hub for both identity and role-based behavior.
   - The `Authenticatable` controller concern centralizes access control across controllers.

8. **Content and admin boundaries**
   - Static/editorial content is split into announcements, FAQs, landing pages, terms, and privacy policy.
   - `admin/announcements` is a distinct namespace, so admin content management is separated from public browsing.
   - `ActionText` is used for rich text content where needed.

9. **Backend services and integrations**
   - The `app/services` layer handles external-data and utility concerns: document fetching, Google spreadsheet access, shop info extraction/insertion, URL handling, and GCP session management.
   - This suggests an import/sync pipeline for shop master data and possibly content enrichment, separate from normal request handling.

10. **Background processing and notifications**
    - The app has background jobs for auto-retiring records and sending cheer messages.
    - Mailers cover account activation, password resets, shop registration, and retirement notifications.
    - The presence of `good_jobs` migration indicates jobs run through a database-backed worker setup rather than an external queue service.

11. **Media and persistence**
    - Active Storage is used for uploaded assets, and ActionText is present for richer content blocks.
    - Most persistent state lives in PostgreSQL through ActiveRecord models; there is no separate domain database or microservice boundary.

12. **UI evolution boundary**
    - Many views and partials exist in both normal and `+v2` variants, and there is a `docs/v2_ui_migration.md`.
    - That means the codebase currently supports two presentation modes over the same backend domain, which is an important diagram boundary: shared models/controllers, parallel view layer.

13. **Operational setup**
    - Development is containerized with Docker/Compose and Dev Container support.
    - CI runs RSpec and RuboCop on pull requests, and main-branch merges deploy automatically to Fly.io via GitHub Actions.
    - Sentry is configured for runtime error monitoring.

14. **How the main data flows connect**
    - Users authenticate → browse shops/records → start or submit a measurement → `Record`/`LineStatus` are persisted → Turbo updates the page → related counts/favorites/likes refresh.
    - Admins and sync tasks import or manage master data/content in the background, while public users consume the same models through the rendered pages and interactive widgets.

Main entry points: [`app/models/user.rb`](https://github.com/moriw0/tyakudon/blob/main/app/models/user.rb) (User), [`app/models/record.rb`](https://github.com/moriw0/tyakudon/blob/main/app/models/record.rb) (Record), [`app/controllers/concerns/authenticatable.rb`](https://github.com/moriw0/tyakudon/blob/main/app/controllers/concerns/authenticatable.rb) (Auth concern), [`app/mailers/application_mailer.rb`](https://github.com/moriw0/tyakudon/blob/main/app/mailers/application_mailer.rb) (Mailers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_auth["Auth & accounts"]
  node_node_authenticatable["Auth concern<br/>controller concern<br/>[authenticatable.rb]"]
  node_node_users_controller["Users<br/>accounts controller"]
  node_node_sessions_controller["Sessions<br/>login controller"]
  node_node_password_resets_controller["Password resets<br/>recovery controller"]
  node_node_account_activations_controller["Activations<br/>activation controller"]
  node_node_omniauth_users_controller["Social login<br/>oauth controller"]
  node_node_user_model[("User<br/>auth model<br/>[user.rb]")]
end

subgraph group_group_core["Ramen measurement"]
  node_node_records_controller["Records<br/>measurement controller"]
  node_node_new_records_controller["New records<br/>start controller"]
  node_node_line_statuses_controller["Line status<br/>queue controller"]
  node_node_cheer_messages_controller["Cheer messages<br/>encouragement controller"]
  node_node_record_model[("Record<br/>measure model<br/>[record.rb]")]
  node_node_line_status_model[("Line status<br/>queue model<br/>[line_status.rb]")]
  node_node_cheer_message_model["Cheer message<br/>message model<br/>[cheer_message.rb]"]
end

subgraph group_group_shop["Shops & discovery"]
  node_node_ramen_shops_controller["Shops<br/>directory controller"]
  node_node_favorites_controller["Favorites<br/>reaction controller"]
  node_node_likes_controller["Likes<br/>reaction controller"]
  node_node_favorite_records_controller["Favorite records<br/>feed controller"]
  node_node_home_controller["Home<br/>browse controller<br/>[home_controller.rb]"]
  node_node_ramen_shop_model[("Ramen shop<br/>shop model<br/>[ramen_shop.rb]")]
  node_node_favorite_model["Favorite<br/>join model<br/>[favorite.rb]"]
  node_node_like_model["Like<br/>join model<br/>[like.rb]"]
end

subgraph group_group_content["Content & admin"]
  node_node_announcements_controller["Announcements<br/>content controller"]
  node_node_admin_announcements_controller["Admin announcements<br/>admin controller"]
  node_node_faqs_controller["FAQs<br/>content controller<br/>[faqs_controller.rb]"]
  node_node_statics_controller["Static pages<br/>content controller"]
  node_node_landing_page_controller["Landing page<br/>marketing controller"]
  node_node_shop_register_request_model["Shop request<br/>submission model"]
  node_node_announcement_model["Announcement<br/>content model<br/>[announcement.rb]"]
  node_node_faq_model["FAQ<br/>content model<br/>[faq.rb]"]
end

subgraph group_group_platform["Platform"]
  node_node_application_controller["Application controller<br/>rails base"]
  node_node_services["Services<br/>integration layer"]
  node_node_jobs["Background jobs<br/>worker layer<br/>[application_job.rb]"]
  node_node_mailers["Mailers<br/>notification layer"]
end

node_node_application_controller -->|"uses"| node_node_authenticatable
node_node_authenticatable -->|"guards"| node_node_users_controller
node_node_authenticatable -->|"guards"| node_node_ramen_shops_controller
node_node_authenticatable -->|"guards"| node_node_records_controller
node_node_users_controller -->|"manages"| node_node_user_model
node_node_sessions_controller -->|"authenticates"| node_node_user_model
node_node_password_resets_controller -->|"updates"| node_node_user_model
node_node_account_activations_controller -->|"activates"| node_node_user_model
node_node_omniauth_users_controller -->|"links"| node_node_user_model
node_node_ramen_shops_controller -->|"reads/writes"| node_node_ramen_shop_model
node_node_home_controller -->|"browses"| node_node_ramen_shop_model
node_node_favorites_controller -->|"toggles"| node_node_favorite_model
node_node_likes_controller -->|"toggles"| node_node_like_model
node_node_favorite_records_controller -->|"lists"| node_node_record_model
node_node_new_records_controller -->|"starts"| node_node_record_model
node_node_records_controller -->|"shows"| node_node_record_model
node_node_records_controller -->|"uses"| node_node_line_status_model
node_node_line_statuses_controller -->|"manages"| node_node_line_status_model
node_node_cheer_messages_controller -->|"renders"| node_node_cheer_message_model
node_node_announcements_controller -->|"publishes"| node_node_announcement_model
node_node_admin_announcements_controller -->|"administers"| node_node_announcement_model
node_node_faqs_controller -->|"edits"| node_node_faq_model
node_node_statics_controller -.->|"pairs with"| node_node_announcement_model
node_node_statics_controller -.->|"shares content layer"| node_node_mailers
node_node_services -->|"syncs"| node_node_ramen_shop_model
node_node_services -->|"imports"| node_node_faq_model
node_node_jobs -->|"retires"| node_node_record_model
node_node_jobs -->|"sends"| node_node_cheer_message_model
node_node_mailers -->|"notifies"| node_node_user_model
node_node_mailers -->|"notifies"| node_node_shop_register_request_model
node_node_mailers -->|"notifies"| node_node_record_model

click node_node_application_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/application_controller.rb"
click node_node_authenticatable "https://github.com/moriw0/tyakudon/blob/main/app/controllers/concerns/authenticatable.rb"
click node_node_users_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/users_controller.rb"
click node_node_sessions_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/sessions_controller.rb"
click node_node_password_resets_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/password_resets_controller.rb"
click node_node_account_activations_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/account_activations_controller.rb"
click node_node_omniauth_users_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/omniauth_users_controller.rb"
click node_node_ramen_shops_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/ramen_shops_controller.rb"
click node_node_favorites_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/favorites_controller.rb"
click node_node_likes_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/likes_controller.rb"
click node_node_favorite_records_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/favorite_records_controller.rb"
click node_node_records_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/records_controller.rb"
click node_node_new_records_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/new_records_controller.rb"
click node_node_line_statuses_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/line_statuses_controller.rb"
click node_node_cheer_messages_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/cheer_messages_controller.rb"
click node_node_announcements_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/announcements_controller.rb"
click node_node_admin_announcements_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/admin/announcements_controller.rb"
click node_node_faqs_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/faqs_controller.rb"
click node_node_statics_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/statics_controller.rb"
click node_node_landing_page_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/landing_page_controller.rb"
click node_node_home_controller "https://github.com/moriw0/tyakudon/blob/main/app/controllers/home_controller.rb"
click node_node_user_model "https://github.com/moriw0/tyakudon/blob/main/app/models/user.rb"
click node_node_ramen_shop_model "https://github.com/moriw0/tyakudon/blob/main/app/models/ramen_shop.rb"
click node_node_record_model "https://github.com/moriw0/tyakudon/blob/main/app/models/record.rb"
click node_node_line_status_model "https://github.com/moriw0/tyakudon/blob/main/app/models/line_status.rb"
click node_node_favorite_model "https://github.com/moriw0/tyakudon/blob/main/app/models/favorite.rb"
click node_node_like_model "https://github.com/moriw0/tyakudon/blob/main/app/models/like.rb"
click node_node_cheer_message_model "https://github.com/moriw0/tyakudon/blob/main/app/models/cheer_message.rb"
click node_node_shop_register_request_model "https://github.com/moriw0/tyakudon/blob/main/app/models/shop_register_request.rb"
click node_node_announcement_model "https://github.com/moriw0/tyakudon/blob/main/app/models/announcement.rb"
click node_node_faq_model "https://github.com/moriw0/tyakudon/blob/main/app/models/faq.rb"
click node_node_services "https://github.com/moriw0/tyakudon/blob/main/app/services/document_fetcher.rb"
click node_node_jobs "https://github.com/moriw0/tyakudon/blob/main/app/jobs/application_job.rb"
click node_node_mailers "https://github.com/moriw0/tyakudon/blob/main/app/mailers/application_mailer.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_authenticatable,node_node_users_controller,node_node_sessions_controller,node_node_password_resets_controller,node_node_account_activations_controller,node_node_omniauth_users_controller,node_node_user_model toneBlue
class node_node_records_controller,node_node_new_records_controller,node_node_line_statuses_controller,node_node_cheer_messages_controller,node_node_record_model,node_node_line_status_model,node_node_cheer_message_model toneAmber
class node_node_ramen_shops_controller,node_node_favorites_controller,node_node_likes_controller,node_node_favorite_records_controller,node_node_home_controller,node_node_ramen_shop_model,node_node_favorite_model,node_node_like_model toneMint
class node_node_announcements_controller,node_node_admin_announcements_controller,node_node_faqs_controller,node_node_statics_controller,node_node_landing_page_controller,node_node_shop_register_request_model,node_node_announcement_model,node_node_faq_model toneRose
class node_node_application_controller,node_node_services,node_node_jobs,node_node_mailers toneIndigo
```

## Components

### Auth & accounts

Login, account recovery, and identity providers.

- [Auth concern](https://github.com/moriw0/tyakudon/blob/main/app/controllers/concerns/authenticatable.rb): controller concern · Reusable authorization and login guards. · `app/controllers/concerns/authenticatable.rb`
- [Users](https://github.com/moriw0/tyakudon/blob/main/app/controllers/users_controller.rb): accounts controller · Profiles, settings, and test-mode behavior. · `app/controllers/users_controller.rb`
- [Sessions](https://github.com/moriw0/tyakudon/blob/main/app/controllers/sessions_controller.rb): login controller · Sign-in and sign-out flow. · `app/controllers/sessions_controller.rb`
- [Password resets](https://github.com/moriw0/tyakudon/blob/main/app/controllers/password_resets_controller.rb): recovery controller · Password reset request and update flow. · `app/controllers/password_resets_controller.rb`
- [Activations](https://github.com/moriw0/tyakudon/blob/main/app/controllers/account_activations_controller.rb): activation controller · Account activation lifecycle. · `app/controllers/account_activations_controller.rb`
- [Social login](https://github.com/moriw0/tyakudon/blob/main/app/controllers/omniauth_users_controller.rb): oauth controller · OmniAuth callback and provider identity handling. · `app/controllers/omniauth_users_controller.rb`
- [User](https://github.com/moriw0/tyakudon/blob/main/app/models/user.rb): auth model · Identity hub for roles, providers, activation, and test mode. · `app/models/user.rb`

### Ramen measurement

Main wait-time and live queue workflow.

- [Records](https://github.com/moriw0/tyakudon/blob/main/app/controllers/records_controller.rb): measurement controller · Record detail, results, and measurement lifecycle. · `app/controllers/records_controller.rb`
- [New records](https://github.com/moriw0/tyakudon/blob/main/app/controllers/new_records_controller.rb): start controller · Starts a new measurement and manages intermediate form updates. · `app/controllers/new_records_controller.rb`
- [Line status](https://github.com/moriw0/tyakudon/blob/main/app/controllers/line_statuses_controller.rb): queue controller · Live queue posting, editing, and Turbo Stream updates. · `app/controllers/line_statuses_controller.rb`
- [Cheer messages](https://github.com/moriw0/tyakudon/blob/main/app/controllers/cheer_messages_controller.rb): encouragement controller · Lightweight encouragement around the waiting experience. · `app/controllers/cheer_messages_controller.rb`
- [Record](https://github.com/moriw0/tyakudon/blob/main/app/models/record.rb): measure model · Wait-time measurement and retirement state. · `app/models/record.rb`
- [Line status](https://github.com/moriw0/tyakudon/blob/main/app/models/line_status.rb): queue model · Current live queue state for a shop. · `app/models/line_status.rb`
- [Cheer message](https://github.com/moriw0/tyakudon/blob/main/app/models/cheer_message.rb): message model · Short supportive message tied to the measurement flow. · `app/models/cheer_message.rb`

### Shops & discovery

Shop directory, location, favorites, and engagement.

- [Shops](https://github.com/moriw0/tyakudon/blob/main/app/controllers/ramen_shops_controller.rb): directory controller · Shop pages, search, nearby lookup, maps, and favorites entrypoints. · `app/controllers/ramen_shops_controller.rb`
- [Favorites](https://github.com/moriw0/tyakudon/blob/main/app/controllers/favorites_controller.rb): reaction controller · User-to-shop favorite toggles. · `app/controllers/favorites_controller.rb`
- [Likes](https://github.com/moriw0/tyakudon/blob/main/app/controllers/likes_controller.rb): reaction controller · User-to-record like toggles. · `app/controllers/likes_controller.rb`
- [Favorite records](https://github.com/moriw0/tyakudon/blob/main/app/controllers/favorite_records_controller.rb): feed controller · Browse and filter saved or favored records. · `app/controllers/favorite_records_controller.rb`
- [Home](https://github.com/moriw0/tyakudon/blob/main/app/controllers/home_controller.rb): browse controller · Signed-in home and search surfaces. · `app/controllers/home_controller.rb`
- [Ramen shop](https://github.com/moriw0/tyakudon/blob/main/app/models/ramen_shop.rb): shop model · Shop master data and location-based attributes. · `app/models/ramen_shop.rb`
- [Favorite](https://github.com/moriw0/tyakudon/blob/main/app/models/favorite.rb): join model · User-to-shop relationship for saved shops. · `app/models/favorite.rb`
- [Like](https://github.com/moriw0/tyakudon/blob/main/app/models/like.rb): join model · User-to-record engagement relationship. · `app/models/like.rb`

### Content & admin

Editorial pages, announcements, FAQs, and admin management.

- [Announcements](https://github.com/moriw0/tyakudon/blob/main/app/controllers/announcements_controller.rb): content controller · Public announcement pages. · `app/controllers/announcements_controller.rb`
- [Admin announcements](https://github.com/moriw0/tyakudon/blob/main/app/controllers/admin/announcements_controller.rb): admin controller · Back-office announcement management. · `app/controllers/admin/announcements_controller.rb`
- [FAQs](https://github.com/moriw0/tyakudon/blob/main/app/controllers/faqs_controller.rb): content controller · Frequently asked questions pages and editing. · `app/controllers/faqs_controller.rb`
- [Static pages](https://github.com/moriw0/tyakudon/blob/main/app/controllers/statics_controller.rb): content controller · Terms and privacy policy pages. · `app/controllers/statics_controller.rb`
- [Landing page](https://github.com/moriw0/tyakudon/blob/main/app/controllers/landing_page_controller.rb): marketing controller · Top-of-funnel landing experience. · `app/controllers/landing_page_controller.rb`
- [Shop request](https://github.com/moriw0/tyakudon/blob/main/app/models/shop_register_request.rb): submission model · Incoming shop registration request. · `app/models/shop_register_request.rb`
- [Announcement](https://github.com/moriw0/tyakudon/blob/main/app/models/announcement.rb): content model · Published announcements with rich text. · `app/models/announcement.rb`
- [FAQ](https://github.com/moriw0/tyakudon/blob/main/app/models/faq.rb): content model · Editable FAQ entries. · `app/models/faq.rb`

### Platform

Jobs, services, frontend behavior, and infrastructure.

- [Application controller](https://github.com/moriw0/tyakudon/blob/main/app/controllers/application_controller.rb): rails base · Shared controller layer and cross-cutting access control. · `app/controllers/application_controller.rb`
- [Services](https://github.com/moriw0/tyakudon/blob/main/app/services/document_fetcher.rb): integration layer · External data fetch, spreadsheet sync, URL handling, and GCP sessions. · `app/services/document_fetcher.rb`
- [Background jobs](https://github.com/moriw0/tyakudon/blob/main/app/jobs/application_job.rb): worker layer · Auto-retirement and cheer-message delivery. · `app/jobs/application_job.rb`
- [Mailers](https://github.com/moriw0/tyakudon/blob/main/app/mailers/application_mailer.rb): notification layer · Account, shop registration, and retirement emails. · `app/mailers/application_mailer.rb`

## Connections

- Application controller → Auth concern: uses · Base controllers share login and permission guards.
- Auth concern → Users: guards · User-related actions depend on shared access control.
- Auth concern → Shops: guards · Directory actions are wrapped by the common auth layer.
- Auth concern → Records: guards · Measurement actions rely on the common auth layer.
- Users → User: manages · Profiles and account flags.
- Sessions → User: authenticates · Credentials resolve to the user hub.
- Password resets → User: updates · Reset tokens and password changes.
- Activations → User: activates · Activation state lives on users.
- Social login → User: links · Provider/uid identities attach to users.
- Shops → Ramen shop: reads/writes · Shop directory and location data.
- Home → Ramen shop: browses · Home/search surfaces surface shops.
- Favorites → Favorite: toggles · Creates and removes shop favorites.
- Likes → Like: toggles · Creates and removes record likes.
- Favorite records → Record: lists · Filtered record feed centers on record data.
- New records → Record: starts · Initiates measurement records.
- Records → Record: shows · Detail and result pages come from records.
- Records → Line status: uses · Recorded measurement is tied to live queue state.
- Line status → Line status: manages · Live queue state is created and updated here.
- Cheer messages → Cheer message: renders · Support messages are surfaced through the controller.
- Announcements → Announcement: publishes · Public announcement pages.
- Admin announcements → Announcement: administers · Admin CRUD over announcements.
- FAQs → FAQ: edits · FAQ content management.
- Static pages → Announcement: pairs with · Editorial content sits alongside static pages and rich text.
- Static pages → Mailers: shares content layer · Policy and legal pages are part of the same public content boundary.
- Services → Ramen shop: syncs · Shop master data import and enrichment.
- Services → FAQ: imports · Content can be fed from external sources or spreadsheets.
- Background jobs → Record: retires · Background job auto-closes stale measurements.
- Background jobs → Cheer message: sends · Background delivery of cheer messages.
- Mailers → User: notifies · Activation and password reset emails.
- Mailers → Shop request: notifies · Registration workflows send shop-request mail.
- Mailers → Record: notifies · Retirement notifications refer back to records.
