# f/mcp-startup-boilerplate architecture

> Architecture diagram of the GitHub repository f/mcp-startup-boilerplate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/f/mcp-startup-boilerplate
- Repository: https://github.com/f/mcp-startup-boilerplate

## Overview

##### Project Type and Purpose
- This is a monolithic, full-stack Rails application boilerplate geared toward building AI-powered web apps.
- It provides user authentication (Devise), an OAuth2 provider (Doorkeeper), payment processing (Stripe), and integrates with Claude AI via the Model Context Protocol (fast-mcp).
- The frontend uses modern Rails asset tooling: Tailwind CSS for styling, Importmap/Hotwire (Turbo + Stimulus) for interactivity.

##### File Structure
- Top-level directories:
- app/: Rails MVC code (controllers, models, views, assets, jobs, mailers, tools, resources).
- config/: Rails and deployment configs (database, environment, OAuth, Stripe, cable/ActionCable).
- bin/, lib/, script/: utility scripts and custom deployment hooks (.kamal).
- db/: schema, migrations, seeds.
- public/: static assets and error pages.
- test/: automated tests.
- Key patterns:
- MVC for web and API endpoints.
- app/tools/ and app/resources/ implement MCP.
- Doorkeeper controllers under app/controllers/doorkeeper handle OAuth flows.
- Webhook controller (app/controllers/webhooks_controller.rb) for Stripe events.
- Configuration/build:
- Dockerfile + .dockerignore for containerization.
- Procfile.dev, Kamal hooks under .kamal/ for deployment automation.
- Importmap, Yarn/Node only for Stimulus controllers.

##### Insights from README
- Rails 8.0.2, Ruby 3.2+, PostgreSQL backend.
- Hotwired frontend (Turbo + Stimulus) with Tailwind CSS.
- Stripe integration for pay-per-use and subscription.
- OAuth2 server supporting multiple grant types and PKCE.
- MCP endpoints expose “tools” (app/tools) and “resources” (app/resources) over SSE or JSON.

##### Main Components & Their Interactions
a. Clients
- Web client (browser) – standard MVC pages, Hotwire streams.
- AI client (Claude) – connects to MCP SSE endpoint to invoke tools/resources.
b. Rails Application
- Web Server (Puma) – serves HTTP(S) requests.
- Controllers
– Devise controllers: user signup/login.
– Doorkeeper controllers: OAuth2 endpoints (/oauth/authorize, /oauth/token, etc.).
– MCP controllers (fast-mcp): /mcp/sse, /mcp/json.
– Webhooks controller: Stripe event webhooks.
- Models & Persistence
– User, Subscription, ToolUsage stored in PostgreSQL.
- MCP Layer
– app/tools/: business logic for AI-invoked “tools.”
– app/resources/: data endpoints for AI client resources.
- Background Jobs (ActiveJob) – handle asynchronous tasks (e.g., sending emails, processing webhooks).
- ActionCable – real-time streams if used (config/cable.yml).
c. External Services
- PostgreSQL – primary database.
- Stripe – payment gateway for charging users, handling subscriptions, invoking webhooks.
- Claude AI – external AI client connecting via MCP protocol.

##### Architectural Patterns & Design Principles
- MVC pattern at core for web UI.
- Separation of concerns between web controllers, API/OAuth controllers, and MCP controllers.
- Layered architecture: Presentation (views + Stimulus), Application (controllers), Domain (models, tools, resources), Infrastructure (Stripe, Doorkeeper, Devise).
- Single codebase monolith with clear component boundaries.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Clients"
        browser["Browser"]:::frontend
        ai["AI Client (Claude)"]:::external
    end

    subgraph "Web/API Layer"
        router["Routes (config/routes.rb)"]:::backend
        puma["Puma Server (config/puma.rb)"]:::backend
        devise_ctrl["Devise Controllers"]:::backend
        doorkeeper_ctrl["Doorkeeper Controllers"]:::backend
        mcp_ctrl["MCP Controllers"]:::backend
        webhook_ctrl["Webhooks Controller"]:::backend
        turbo["Turbo (Hotwire)"]:::frontend
        stimulus["Stimulus Controllers"]:::frontend
        tailwind["Tailwind CSS"]:::frontend
        importmap["Importmap (config/importmap.rb)"]:::frontend
    end

    subgraph "Domain Layer"
        user_model["User Model"]:::backend
        subscription["UserSubscription Model"]:::backend
        toolusage["ToolUsage Model"]:::backend
        tools["Tools (app/tools/)"]:::backend
        resources["Resources (app/resources/)"]:::backend
        activejob["ActiveJob"]:::backend
        mailer["Mailers"]:::backend
    end

    subgraph "External Services"
        db["PostgreSQL"]:::external
        stripe["Stripe"]:::external
        claude["Claude AI"]:::external
        container["Docker & Kamal"]:::external
    end

    browser -->|HTTP| router
    router --> puma
    puma --> devise_ctrl
    puma --> doorkeeper_ctrl
    puma --> mcp_ctrl
    puma --> webhook_ctrl
    puma --> turbo
    puma --> stimulus
    puma --> importmap
    puma --> tailwind
    puma --> container

    devise_ctrl -->|DB| user_model
    doorkeeper_ctrl -->|DB| user_model
    doorkeeper_ctrl -->|DB| subscription
    mcp_ctrl --> tools
    mcp_ctrl --> resources
    tools -->|DB| db
    resources -->|DB| db
    mcp_ctrl -->|SSE/JSON| ai
    ai -->|Invoke MCP| mcp_ctrl

    webhook_ctrl -->|enqueue| activejob
    webhook_ctrl -->|charges| stripe
    stripe -->|webhook| webhook_ctrl
    activejob -->|DB| db
    subscription -->|DB| db
    toolusage -->|DB| db
    mailer --> activejob

    router -->|OAuth| doorkeeper_ctrl

    click user_model "https://github.com/f/mcp-startup-boilerplate/blob/main/app/models/user.rb"
    click router "https://github.com/f/mcp-startup-boilerplate/blob/main/config/routes.rb"
    click puma "https://github.com/f/mcp-startup-boilerplate/blob/main/config/puma.rb"
    click doorkeeper_ctrl "https://github.com/f/mcp-startup-boilerplate/tree/main/app/controllers/doorkeeper/"
    click webhook_ctrl "https://github.com/f/mcp-startup-boilerplate/blob/main/app/controllers/webhooks_controller.rb"
    click subscription "https://github.com/f/mcp-startup-boilerplate/blob/main/app/models/user_subscription.rb"
    click tools "https://github.com/f/mcp-startup-boilerplate/tree/main/app/tools/"
    click resources "https://github.com/f/mcp-startup-boilerplate/tree/main/app/resources/"
    click importmap "https://github.com/f/mcp-startup-boilerplate/blob/main/config/importmap.rb"
    click stimulus "https://github.com/f/mcp-startup-boilerplate/tree/main/app/javascript/controllers/"
    click tailwind "https://github.com/f/mcp-startup-boilerplate/blob/main/app/assets/tailwind/application.css"
    click activejob "https://github.com/f/mcp-startup-boilerplate/blob/main/app/jobs/application_job.rb"
    click mailer "https://github.com/f/mcp-startup-boilerplate/blob/main/app/mailers/application_mailer.rb"
    click db "https://github.com/f/mcp-startup-boilerplate/tree/main/db/migrate/"
    click container "https://github.com/f/mcp-startup-boilerplate/tree/main/Dockerfile"

    classDef frontend fill:#cce5ff,stroke:#339,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#2a5934,stroke-width:1px
    classDef external fill:#fff3cd,stroke:#9b6,stroke-width:1px
```
