# v2-mason/mason-os architecture

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

- Interactive diagram: https://gitdiagram.com/v2-mason/mason-os
- Repository: https://github.com/v2-mason/mason-os

## Overview

#### Purpose and Repository Shape
This is an operations/knowledge workspace rather than a single deployable application. It combines personal/project governance, process documentation, and one implemented production system. Top-level portfolio routing is represented by `PROJECTS.yaml`, `SYSTEMS.yaml`, and `06 Systems/README.md`.

#### Primary Executable System: DML-Production
`06 Systems/DML-Production` is the material software system: a customer-inquiry pipeline that accepts Shopify storefront submissions, validates and deduplicates them, records delivery state, and creates/updates CRM data. System-level intent, decisions, and boundaries live in:
- `06 Systems/DML-Production/SYSTEM.md`
- `06 Systems/DML-Production/DECISIONS.md`
- `06 Systems/DML-Production/docs/boundaries/02-TARGET-BOUNDARIES.md`

#### Storefront and Shopify Entry Points
The customer-facing entry point is a Shopify theme section and page template, with a Shopify app configuration alongside it:
- `06 Systems/DML-Production/apps/inquiry-storefront/sections/inquiry-form.liquid`
- `06 Systems/DML-Production/apps/inquiry-storefront/templates/page.inquiry.json`
- `06 Systems/DML-Production/apps/inquiry-shopify-app/shopify.app.toml`

The storefront produces an inquiry payload; it is a presentation/integration boundary, not the owner of CRM mapping or persistence policy.

#### Inquiry Integration Domain Pipeline
`inquiry-integration` contains the reusable domain workflow. Its public entry point accepts an inquiry envelope, normalizes and schema-validates it, establishes identity and company matching, enforces idempotency, and invokes a CRM adapter:
- `06 Systems/DML-Production/apps/inquiry-integration/src/index.js`
- `06 Systems/DML-Production/apps/inquiry-integration/src/domain/submit-inquiry.js`
- `06 Systems/DML-Production/apps/inquiry-integration/schema/validate.js`

Canonical JSON and digests support stable idempotency/conflict handling. Receipt and delivery stores isolate submission state from external CRM effects:
- `06 Systems/DML-Production/apps/inquiry-integration/src/domain/idempotency.js`
- `06 Systems/DML-Production/apps/inquiry-integration/src/domain/receipt-store.js`
- `06 Systems/DML-Production/apps/inquiry-integration/src/domain/delivery-store.js`

#### API Runtime, Security, and Audit Boundary
`inquiry-api` is the deployable Node.js HTTP service. Server/runtime setup delegates requests to an application layer, with separate intake and scheduler authentication, rate limiting, configuration, and audit CLI:
- `06 Systems/DML-Production/apps/inquiry-api/src/server.js`
- `06 Systems/DML-Production/apps/inquiry-api/src/http-handler.js`
- `06 Systems/DML-Production/apps/inquiry-api/src/application.js`

Operational controls are explicit at the HTTP boundary:
- `06 Systems/DML-Production/apps/inquiry-api/src/intake-auth.js`
- `06 Systems/DML-Production/apps/inquiry-api/src/scheduler-auth.js`
- `06 Systems/DML-Production/apps/inquiry-api/src/rate-limit.js`

#### External Services and Persistence
The system integrates with HubSpot through a dedicated transport/adapter boundary and can persist its ledger in Firestore; an in-memory ledger supports local/test runtime:
- `06 Systems/DML-Production/apps/inquiry-api/src/hubspot-crm-adapter.js`
- `06 Systems/DML-Production/apps/inquiry-api/src/hubspot-transport.js`
- `06 Systems/DML-Production/apps/inquiry-api/src/firestore-ledger.js`

Container deployment is indicated by `06 Systems/DML-Production/apps/Dockerfile`; project documentation references Cloud Run identity boundaries in `03 Projects/生产自动化采集/01 调研与接口/Developer Mode 与 Cloud Run 身份边界.md`.

#### Operational-Process Project System
`03 Projects/打通AM需求到生产放行流程 V1.0` defines the governed AM requirement-to-production-release operating model around HubSpot and Notion. Its core stages are gates 0–6, role/RACI controls, data contracts, technical/DfAM review, capability selection, and BOM/routing release:
- `03 Projects/打通AM需求到生产放行流程 V1.0/01 流程与Gate设计/AM端到端Operating-Model.md`
- `03 Projects/打通AM需求到生产放行流程 V1.0/02 表单与记录规范/S0-HubSpot到Validation-Case-Intake数据契约.md`
- `03 Projects/打通AM需求到生产放行流程 V1.0/02 表单与记录规范/T6-BOM-Routing质量策划与放行交接.md`

#### Secondary Finance Model
`03 Projects/财务系统建立` contains a separate Python financial-model toolchain: database construction, cost/product/company modeling, and quote tooling:
- `03 Projects/财务系统建立/01 模型/scripts/build_finance_db.py`
- `03 Projects/财务系统建立/01 模型/scripts/cost_engine.py`
- `03 Projects/财务系统建立/01 模型/scripts/run_company_model.py`

Main entry points: [`06 Systems/DML-Production/apps/inquiry-integration/src/domain/submit-inquiry.js`](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/domain/submit-inquiry.js) (Submit inquiry), [`06 Systems/DML-Production/apps/inquiry-api/src/server.js`](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/server.js) (Inquiry API), [`03 Projects/打通AM需求到生产放行流程 V1.0/01 流程与Gate设计/AM端到端Operating-Model.md`](https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E6%89%93%E9%80%9AAM%E9%9C%80%E6%B1%82%E5%88%B0%E7%94%9F%E4%BA%A7%E6%94%BE%E8%A1%8C%E6%B5%81%E7%A8%8B%20V1.0/01%20%E6%B5%81%E7%A8%8B%E4%B8%8EGate%E8%AE%BE%E8%AE%A1/AM%E7%AB%AF%E5%88%B0%E7%AB%AFOperating-Model.md) (Gates 0–6 operating model), [`PROJECTS.yaml`](https://github.com/v2-mason/mason-os/blob/main/PROJECTS.yaml) (Portfolio routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dml["DML-Production"]
  node_dml_system["System boundaries<br/>system documentation<br/>[SYSTEM.md]"]
  node_storefront["Shopify inquiry form<br/>Shopify theme"]
  node_shopify_app["Shopify app config<br/>[shopify.app.toml]"]
  node_api_runtime["Inquiry API<br/>Node HTTP service<br/>[server.js]"]
  node_http_boundary["HTTP security boundary<br/>request handler<br/>[http-handler.js]"]
  node_application["API application<br/>application layer<br/>[application.js]"]
  node_integration["Inquiry integration<br/>domain workflow<br/>[index.js]"]
  node_submission["Submit inquiry<br/>domain service<br/>[submit-inquiry.js]"]
  node_validation["Schema validation<br/>validation boundary"]
  node_idempotency["Idempotency control<br/>domain policy<br/>[idempotency.js]"]
  node_ledger[("Receipt &amp; delivery ledger<br/>submission state<br/>[receipt-store.js]")]
  node_firestore[("Firestore ledger<br/>persistence adapter")]
  node_hubspot_adapter["HubSpot CRM adapter"]
  node_hubspot[("HubSpot<br/>external CRM")]
  node_container["Container deployment<br/>Docker image"]
end

subgraph group_operations["AM Release Process"]
  node_operating_model["Gates 0–6 operating model<br/>process governance"]
  node_intake_contract["HubSpot intake contract<br/>data contract"]
  node_release_handoff["BOM/routing release<br/>release handoff"]
end

subgraph group_finance["Finance Model"]
  node_finance_db[("Finance database build<br/>Python database builder")]
  node_cost_engine["Cost engine<br/>Python model<br/>[cost_engine.py]"]
  node_company_model["Company model runner<br/>Python runner"]
end

node_portfolio["Portfolio routing<br/>workspace index<br/>[PROJECTS.yaml]"]

node_portfolio -->|"indexes"| node_dml_system
node_portfolio -->|"indexes"| node_operating_model
node_storefront -->|"submits inquiry"| node_api_runtime
node_shopify_app -.->|"supports"| node_storefront
node_api_runtime -->|"serves through"| node_http_boundary
node_http_boundary -->|"authorized requests"| node_application
node_application -->|"invokes"| node_integration
node_integration -->|"starts workflow"| node_submission
node_submission -->|"validates"| node_validation
node_submission -->|"deduplicates"| node_idempotency
node_idempotency -->|"records state"| node_ledger
node_ledger -->|"persists via"| node_firestore
node_submission -->|"delivers CRM changes"| node_hubspot_adapter
node_hubspot_adapter -->|"creates or updates"| node_hubspot
node_container -->|"packages"| node_api_runtime
node_intake_contract -->|"governs Gate 0 intake"| node_operating_model
node_operating_model -->|"culminates in"| node_release_handoff
node_hubspot -.->|"source data"| node_intake_contract
node_finance_db -->|"provides model data"| node_cost_engine
node_cost_engine -->|"feeds"| node_company_model

click node_portfolio "https://github.com/v2-mason/mason-os/blob/main/PROJECTS.yaml"
click node_dml_system "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/SYSTEM.md"
click node_storefront "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-storefront/sections/inquiry-form.liquid"
click node_shopify_app "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-shopify-app/shopify.app.toml"
click node_api_runtime "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/server.js"
click node_http_boundary "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/http-handler.js"
click node_application "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/application.js"
click node_integration "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/index.js"
click node_submission "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/domain/submit-inquiry.js"
click node_idempotency "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/domain/idempotency.js"
click node_ledger "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/domain/receipt-store.js"
click node_firestore "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/firestore-ledger.js"
click node_hubspot_adapter "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/hubspot-crm-adapter.js"
click node_container "https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/Dockerfile"
click node_operating_model "https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E6%89%93%E9%80%9AAM%E9%9C%80%E6%B1%82%E5%88%B0%E7%94%9F%E4%BA%A7%E6%94%BE%E8%A1%8C%E6%B5%81%E7%A8%8B%20V1.0/01%20%E6%B5%81%E7%A8%8B%E4%B8%8EGate%E8%AE%BE%E8%AE%A1/AM%E7%AB%AF%E5%88%B0%E7%AB%AFOperating-Model.md"
click node_intake_contract "https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E6%89%93%E9%80%9AAM%E9%9C%80%E6%B1%82%E5%88%B0%E7%94%9F%E4%BA%A7%E6%94%BE%E8%A1%8C%E6%B5%81%E7%A8%8B%20V1.0/02%20%E8%A1%A8%E5%8D%95%E4%B8%8E%E8%AE%B0%E5%BD%95%E8%A7%84%E8%8C%83/S0-HubSpot%E5%88%B0Validation-Case-Intake%E6%95%B0%E6%8D%AE%E5%A5%91%E7%BA%A6.md"
click node_release_handoff "https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E6%89%93%E9%80%9AAM%E9%9C%80%E6%B1%82%E5%88%B0%E7%94%9F%E4%BA%A7%E6%94%BE%E8%A1%8C%E6%B5%81%E7%A8%8B%20V1.0/02%20%E8%A1%A8%E5%8D%95%E4%B8%8E%E8%AE%B0%E5%BD%95%E8%A7%84%E8%8C%83/T6-BOM-Routing%E8%B4%A8%E9%87%8F%E7%AD%96%E5%88%92%E4%B8%8E%E6%94%BE%E8%A1%8C%E4%BA%A4%E6%8E%A5.md"
click node_finance_db "https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E8%B4%A2%E5%8A%A1%E7%B3%BB%E7%BB%9F%E5%BB%BA%E7%AB%8B/01%20%E6%A8%A1%E5%9E%8B/scripts/build_finance_db.py"
click node_cost_engine "https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E8%B4%A2%E5%8A%A1%E7%B3%BB%E7%BB%9F%E5%BB%BA%E7%AB%8B/01%20%E6%A8%A1%E5%9E%8B/scripts/cost_engine.py"
click node_company_model "https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E8%B4%A2%E5%8A%A1%E7%B3%BB%E7%BB%9F%E5%BB%BA%E7%AB%8B/01%20%E6%A8%A1%E5%9E%8B/scripts/run_company_model.py"

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_dml_system,node_storefront,node_shopify_app,node_api_runtime,node_http_boundary,node_application,node_integration,node_submission,node_validation,node_idempotency,node_ledger,node_firestore,node_hubspot_adapter,node_hubspot,node_container toneBlue
class node_operating_model,node_intake_contract,node_release_handoff toneAmber
class node_finance_db,node_cost_engine,node_company_model toneMint
class node_portfolio toneNeutral
```

## Components

### DML-Production

Customer inquiry pipeline.

- [System boundaries](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/SYSTEM.md): system documentation · Defines DML intent and integration boundaries. · `06 Systems/DML-Production/SYSTEM.md`
- [Shopify inquiry form](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-storefront/sections/inquiry-form.liquid): Shopify theme · Customer-facing inquiry entry point. · `06 Systems/DML-Production/apps/inquiry-storefront/sections/inquiry-form.liquid`
- [Shopify app config](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-shopify-app/shopify.app.toml): Shopify app · `06 Systems/DML-Production/apps/inquiry-shopify-app/shopify.app.toml`
- [Inquiry API](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/server.js): Node HTTP service · Deployable runtime for intake and scheduled delivery. · `06 Systems/DML-Production/apps/inquiry-api/src/server.js`
- [HTTP security boundary](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/http-handler.js): request handler · Applies intake/scheduler auth and rate limiting. · `06 Systems/DML-Production/apps/inquiry-api/src/http-handler.js`
- [API application](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/application.js): application layer · Delegates API operations to the integration workflow. · `06 Systems/DML-Production/apps/inquiry-api/src/application.js`
- [Inquiry integration](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/index.js): domain workflow · Public reusable inquiry-processing entry point. · `06 Systems/DML-Production/apps/inquiry-integration/src/index.js`
- [Submit inquiry](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/domain/submit-inquiry.js): domain service · Normalizes, identifies, matches, and submits inquiries. · `06 Systems/DML-Production/apps/inquiry-integration/src/domain/submit-inquiry.js`
- **Schema validation**: validation boundary
- [Idempotency control](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/domain/idempotency.js): domain policy · Uses canonical payload digests for replay and conflict handling. · `06 Systems/DML-Production/apps/inquiry-integration/src/domain/idempotency.js`
- [Receipt & delivery ledger](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-integration/src/domain/receipt-store.js): submission state · Separates receipt state from external delivery effects. · `06 Systems/DML-Production/apps/inquiry-integration/src/domain/receipt-store.js`
- [Firestore ledger](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/firestore-ledger.js): persistence adapter · Production ledger persistence. · `06 Systems/DML-Production/apps/inquiry-api/src/firestore-ledger.js`
- [HubSpot CRM adapter](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/inquiry-api/src/hubspot-crm-adapter.js): CRM adapter · Owns CRM mapping and transport integration. · `06 Systems/DML-Production/apps/inquiry-api/src/hubspot-crm-adapter.js`
- **HubSpot**: external CRM
- [Container deployment](https://github.com/v2-mason/mason-os/blob/main/06%20Systems/DML-Production/apps/Dockerfile): Docker image · Deployment artifact for the API runtime. · `06 Systems/DML-Production/apps/Dockerfile`

### AM Release Process

Governed requirement-to-production release model.

- [Gates 0–6 operating model](https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E6%89%93%E9%80%9AAM%E9%9C%80%E6%B1%82%E5%88%B0%E7%94%9F%E4%BA%A7%E6%94%BE%E8%A1%8C%E6%B5%81%E7%A8%8B%20V1.0/01%20%E6%B5%81%E7%A8%8B%E4%B8%8EGate%E8%AE%BE%E8%AE%A1/AM%E7%AB%AF%E5%88%B0%E7%AB%AFOperating-Model.md): process governance · AM requirement-to-production release stages and role controls. · `03 Projects/打通AM需求到生产放行流程 V1.0/01 流程与Gate设计/AM端到端Operating-Model.md`
- [HubSpot intake contract](https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E6%89%93%E9%80%9AAM%E9%9C%80%E6%B1%82%E5%88%B0%E7%94%9F%E4%BA%A7%E6%94%BE%E8%A1%8C%E6%B5%81%E7%A8%8B%20V1.0/02%20%E8%A1%A8%E5%8D%95%E4%B8%8E%E8%AE%B0%E5%BD%95%E8%A7%84%E8%8C%83/S0-HubSpot%E5%88%B0Validation-Case-Intake%E6%95%B0%E6%8D%AE%E5%A5%91%E7%BA%A6.md): data contract · Defines HubSpot-to-validation-case intake data. · `03 Projects/打通AM需求到生产放行流程 V1.0/02 表单与记录规范/S0-HubSpot到Validation-Case-Intake数据契约.md`
- [BOM/routing release](https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E6%89%93%E9%80%9AAM%E9%9C%80%E6%B1%82%E5%88%B0%E7%94%9F%E4%BA%A7%E6%94%BE%E8%A1%8C%E6%B5%81%E7%A8%8B%20V1.0/02%20%E8%A1%A8%E5%8D%95%E4%B8%8E%E8%AE%B0%E5%BD%95%E8%A7%84%E8%8C%83/T6-BOM-Routing%E8%B4%A8%E9%87%8F%E7%AD%96%E5%88%92%E4%B8%8E%E6%94%BE%E8%A1%8C%E4%BA%A4%E6%8E%A5.md): release handoff · Quality planning and production-release handoff. · `03 Projects/打通AM需求到生产放行流程 V1.0/02 表单与记录规范/T6-BOM-Routing质量策划与放行交接.md`

### Finance Model

Python financial modeling toolchain.

- [Finance database build](https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E8%B4%A2%E5%8A%A1%E7%B3%BB%E7%BB%9F%E5%BB%BA%E7%AB%8B/01%20%E6%A8%A1%E5%9E%8B/scripts/build_finance_db.py): Python database builder · `03 Projects/财务系统建立/01 模型/scripts/build_finance_db.py`
- [Cost engine](https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E8%B4%A2%E5%8A%A1%E7%B3%BB%E7%BB%9F%E5%BB%BA%E7%AB%8B/01%20%E6%A8%A1%E5%9E%8B/scripts/cost_engine.py): Python model · Cost, product, and company modeling. · `03 Projects/财务系统建立/01 模型/scripts/cost_engine.py`
- [Company model runner](https://github.com/v2-mason/mason-os/blob/main/03%20Projects/%E8%B4%A2%E5%8A%A1%E7%B3%BB%E7%BB%9F%E5%BB%BA%E7%AB%8B/01%20%E6%A8%A1%E5%9E%8B/scripts/run_company_model.py): Python runner · Runs company-level financial model and quote tooling. · `03 Projects/财务系统建立/01 模型/scripts/run_company_model.py`

### Other components

- [Portfolio routing](https://github.com/v2-mason/mason-os/blob/main/PROJECTS.yaml): workspace index · Routes projects and systems. · `PROJECTS.yaml`

## Connections

- Portfolio routing → System boundaries: indexes
- Portfolio routing → Gates 0–6 operating model: indexes
- Shopify inquiry form → Inquiry API: submits inquiry
- Shopify app config → Shopify inquiry form: supports
- Inquiry API → HTTP security boundary: serves through
- HTTP security boundary → API application: authorized requests
- API application → Inquiry integration: invokes
- Inquiry integration → Submit inquiry: starts workflow
- Submit inquiry → Schema validation: validates
- Submit inquiry → Idempotency control: deduplicates
- Idempotency control → Receipt & delivery ledger: records state
- Receipt & delivery ledger → Firestore ledger: persists via
- Submit inquiry → HubSpot CRM adapter: delivers CRM changes
- HubSpot CRM adapter → HubSpot: creates or updates
- Container deployment → Inquiry API: packages
- HubSpot intake contract → Gates 0–6 operating model: governs Gate 0 intake
- Gates 0–6 operating model → BOM/routing release: culminates in
- HubSpot → HubSpot intake contract: source data
- Finance database build → Cost engine: provides model data
- Cost engine → Company model runner: feeds