# bullet-train-co/bullet_train architecture

> Architecture diagram of the GitHub repository bullet-train-co/bullet_train, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bullet-train-co/bullet_train
- Repository: https://github.com/bullet-train-co/bullet_train

## Overview

This is a Bullet Train Rails application template for a multi-user, team-based product. The primary workflow is account users managing teams, memberships, and invitations; the template also exposes versioned APIs and a Zapier integration for OAuth, resource creation, and event triggers. Admin resources, address data, browser-side Stimulus/Action Cable support, and OAuth scaffolding are additional capabilities. The excerpts show Zapier’s API/webhook requests and frontend module wiring; most Rails controller-to-model and route behavior was not sampled, so those links are omitted.

Main entry points: [`zapier/index.js`](https://github.com/bullet-train-co/bullet_train/blob/main/zapier/index.js) (Zapier App), [`app/controllers/api/v1`](https://github.com/bullet-train-co/bullet_train/tree/main/app/controllers/api/v1) (Versioned API), [`app/javascript/application.js`](https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/application.js) (Browser Application), [`zapier/authentication.js`](https://github.com/bullet-train-co/bullet_train/blob/main/zapier/authentication.js) (Zapier OAuth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_accounts["Accounts and Teams"]
  node_user["Users<br/>[user.rb]"]
  node_team["Teams<br/>[team.rb]"]
  node_membership["Memberships<br/>[membership.rb]"]
  node_invitation["Invitations<br/>[invitation.rb]"]
  node_address["Address Data<br/>[address.rb]"]
end

subgraph group_interfaces["Application Interfaces"]
  node_account["Account UI"]
  node_public["Public Pages<br/>[home_controller.rb]"]
  node_api["Versioned API"]
  node_admin["Admin UI"]
  node_adminresources["Admin Resources<br/>[team.rb]"]
  node_frontend["Browser Application<br/>[application.js]"]
  node_stimulus["Stimulus Controllers<br/>[index.js]"]
  node_cable["Cable Consumer<br/>[consumer.js]"]
  node_timezone["Timezone Support<br/>[jstz.js]"]
end

subgraph group_integrations["Integrations"]
  node_zapier["Zapier App<br/>[index.js]"]
  node_zapauth["Zapier OAuth<br/>[authentication.js]"]
  node_zapcreate["Zapier Creates"]
  node_zaptrigger["Zapier Triggers"]
  node_oauthsupport["OAuth Scaffolding"]
end

subgraph group_runtime["Application Runtime"]
  node_database[("Relational Database<br/>[schema.rb]")]
  node_jobs["Background Jobs<br/>[application_job.rb]"]
end

node_actor(("Product User"))
node_zapierservice(("Zapier Platform"))
node_webhooks(("Outgoing Webhooks"))

node_frontend -->|"loads"| node_stimulus
node_frontend -->|"loads"| node_cable
node_frontend -->|"loads"| node_timezone
node_stimulus -->|"initializes"| node_cable
node_zapier -->|"registers"| node_zapauth
node_zapier -->|"registers"| node_zapcreate
node_zapier -->|"registers"| node_zaptrigger
node_zapauth -->|"requests OAuth"| node_api
node_zapauth -->|"tests identity"| node_api
node_zapcreate -->|"creates resource"| node_api
node_zaptrigger -->|"lists resources"| node_api
node_zaptrigger -->|"subscribes"| node_webhooks
node_zapierservice -.->|"uses integration"| node_zapier
node_actor -.->|"uses account"| node_account

click node_user "https://github.com/bullet-train-co/bullet_train/blob/main/app/models/user.rb"
click node_team "https://github.com/bullet-train-co/bullet_train/blob/main/app/models/team.rb"
click node_membership "https://github.com/bullet-train-co/bullet_train/blob/main/app/models/membership.rb"
click node_invitation "https://github.com/bullet-train-co/bullet_train/blob/main/app/models/invitation.rb"
click node_address "https://github.com/bullet-train-co/bullet_train/blob/main/app/models/address.rb"
click node_account "https://github.com/bullet-train-co/bullet_train/tree/main/app/controllers/account"
click node_public "https://github.com/bullet-train-co/bullet_train/blob/main/app/controllers/public/home_controller.rb"
click node_api "https://github.com/bullet-train-co/bullet_train/tree/main/app/controllers/api/v1"
click node_admin "https://github.com/bullet-train-co/bullet_train/tree/main/app/controllers/avo"
click node_adminresources "https://github.com/bullet-train-co/bullet_train/blob/main/app/avo/resources/team.rb"
click node_frontend "https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/application.js"
click node_stimulus "https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/controllers/index.js"
click node_cable "https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/channels/consumer.js"
click node_timezone "https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/support/jstz.js"
click node_zapier "https://github.com/bullet-train-co/bullet_train/blob/main/zapier/index.js"
click node_zapauth "https://github.com/bullet-train-co/bullet_train/blob/main/zapier/authentication.js"
click node_zapcreate "https://github.com/bullet-train-co/bullet_train/blob/main/zapier/creates/create_scaffolding_completely_concrete_tangible_thing.js"
click node_zaptrigger "https://github.com/bullet-train-co/bullet_train/blob/main/zapier/triggers/scaffolding_completely_concrete_tangible_thing_created.js"
click node_oauthsupport "https://github.com/bullet-train-co/bullet_train/blob/main/lib/bullet_train_oauth_scaffolder_support.rb"
click node_database "https://github.com/bullet-train-co/bullet_train/blob/main/db/schema.rb"
click node_jobs "https://github.com/bullet-train-co/bullet_train/blob/main/app/jobs/application_job.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_user,node_team,node_membership,node_invitation,node_address,node_actor toneBlue
class node_account,node_public,node_api,node_admin,node_adminresources,node_frontend,node_stimulus,node_cable,node_timezone toneAmber
class node_zapier,node_zapauth,node_zapcreate,node_zaptrigger,node_oauthsupport,node_zapierservice,node_webhooks toneMint
class node_database,node_jobs toneRose
```

## Components

### Accounts and Teams

- [Users](https://github.com/bullet-train-co/bullet_train/blob/main/app/models/user.rb): `app/models/user.rb`
- [Teams](https://github.com/bullet-train-co/bullet_train/blob/main/app/models/team.rb): `app/models/team.rb`
- [Memberships](https://github.com/bullet-train-co/bullet_train/blob/main/app/models/membership.rb): `app/models/membership.rb`
- [Invitations](https://github.com/bullet-train-co/bullet_train/blob/main/app/models/invitation.rb): `app/models/invitation.rb`
- [Address Data](https://github.com/bullet-train-co/bullet_train/blob/main/app/models/address.rb): `app/models/address.rb`

### Application Interfaces

- [Account UI](https://github.com/bullet-train-co/bullet_train/tree/main/app/controllers/account): `app/controllers/account`
- [Public Pages](https://github.com/bullet-train-co/bullet_train/blob/main/app/controllers/public/home_controller.rb): `app/controllers/public/home_controller.rb`
- [Versioned API](https://github.com/bullet-train-co/bullet_train/tree/main/app/controllers/api/v1): `app/controllers/api/v1`
- [Admin UI](https://github.com/bullet-train-co/bullet_train/tree/main/app/controllers/avo): `app/controllers/avo`
- [Admin Resources](https://github.com/bullet-train-co/bullet_train/blob/main/app/avo/resources/team.rb): `app/avo/resources/team.rb`
- [Browser Application](https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/application.js): `app/javascript/application.js`
- [Stimulus Controllers](https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/controllers/index.js): `app/javascript/controllers/index.js`
- [Cable Consumer](https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/channels/consumer.js): `app/javascript/channels/consumer.js`
- [Timezone Support](https://github.com/bullet-train-co/bullet_train/blob/main/app/javascript/support/jstz.js): `app/javascript/support/jstz.js`

### Integrations

- [Zapier App](https://github.com/bullet-train-co/bullet_train/blob/main/zapier/index.js): `zapier/index.js`
- [Zapier OAuth](https://github.com/bullet-train-co/bullet_train/blob/main/zapier/authentication.js): `zapier/authentication.js`
- [Zapier Creates](https://github.com/bullet-train-co/bullet_train/blob/main/zapier/creates/create_scaffolding_completely_concrete_tangible_thing.js): `zapier/creates/create_scaffolding_completely_concrete_tangible_thing.js`
- [Zapier Triggers](https://github.com/bullet-train-co/bullet_train/blob/main/zapier/triggers/scaffolding_completely_concrete_tangible_thing_created.js): `zapier/triggers/scaffolding_completely_concrete_tangible_thing_created.js`
- [OAuth Scaffolding](https://github.com/bullet-train-co/bullet_train/blob/main/lib/bullet_train_oauth_scaffolder_support.rb): `lib/bullet_train_oauth_scaffolder_support.rb`

### Application Runtime

- [Relational Database](https://github.com/bullet-train-co/bullet_train/blob/main/db/schema.rb): `db/schema.rb`
- [Background Jobs](https://github.com/bullet-train-co/bullet_train/blob/main/app/jobs/application_job.rb): `app/jobs/application_job.rb`

### Other components

- **Product User**
- **Zapier Platform**
- **Outgoing Webhooks**

## Connections

- Browser Application → Stimulus Controllers: loads (evidence: `app/javascript/application.js`)
- Browser Application → Cable Consumer: loads (evidence: `app/javascript/application.js`)
- Browser Application → Timezone Support: loads (evidence: `app/javascript/application.js`)
- Stimulus Controllers → Cable Consumer: initializes (evidence: `app/javascript/controllers/index.js`)
- Zapier App → Zapier OAuth: registers (evidence: `zapier/index.js`)
- Zapier App → Zapier Creates: registers (evidence: `zapier/index.js`)
- Zapier App → Zapier Triggers: registers (evidence: `zapier/index.js`)
- Zapier OAuth → Versioned API: requests OAuth (evidence: `zapier/authentication.js`)
- Zapier OAuth → Versioned API: tests identity (evidence: `zapier/authentication.js`)
- Zapier Creates → Versioned API: creates resource (evidence: `zapier/creates/create_scaffolding_completely_concrete_tangible_thing.js`)
- Zapier Triggers → Versioned API: lists resources (evidence: `zapier/triggers/scaffolding_completely_concrete_tangible_thing_created.js`)
- Zapier Triggers → Outgoing Webhooks: subscribes (evidence: `zapier/triggers/scaffolding_completely_concrete_tangible_thing_created.js`)
- Zapier Platform → Zapier App: uses integration
- Product User → Account UI: uses account