# aocgithub/aoc-estimate-calculator-app architecture

> Architecture diagram of the GitHub repository aocgithub/aoc-estimate-calculator-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aocgithub/aoc-estimate-calculator-app
- Repository: https://github.com/aocgithub/aoc-estimate-calculator-app

## Overview

Always Open Commerce Estimator is a React-based business-intake and fixed-price estimation product. Visitors pass an access gate, enter business details, organize a project description, answer editable scope questions, and receive a server-calculated estimate; optional voice input, AI assistance, and consent-based profile reuse/saving extend that flow. The graph also preserves pricing rules, access controls, and profile persistence as distinct capabilities. Some API and feature implementations were not sampled, so their connections are included only where the README or source index supports them.

Main entry points: [`src/App.jsx`](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/App.jsx) (App entry), [`server/api-handlers.mjs`](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/api-handlers.mjs) (Access handlers), [`src/features/calculator/Calculator.jsx`](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/calculator/Calculator.jsx) (Calculator form), [`public/journey-engine.js`](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/journey-engine.js) (Journey engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_app["App entry<br/>[App.jsx]"]
end

subgraph group_estimate["Estimation"]
  node_calculator["Calculator form<br/>[Calculator.jsx]"]
  node_estimator["Estimator state<br/>[useEstimator.js]"]
  node_pricing["Approved pricing"]
  node_pricing_bank["Question bank<br/>[approved-bank.js]"]
  node_commercial["Commercial rules<br/>[commercial.js]"]
  node_journey_api["Journey API<br/>[calculate.mjs]"]
  node_journey_calc["Journey calculation"]
  node_journey_engine["Journey engine<br/>[journey-engine.js]"]
  node_base_engine["Pricing engine<br/>[engine.js]"]
  node_estimate_records[("Estimate records")]
end

subgraph group_access["Access and intake"]
  node_access_ui["Access gate UI<br/>[AccessGate.jsx]"]
  node_access_state["Access state<br/>[useAccessGate.js]"]
  node_access_api["Access handlers<br/>[api-handlers.mjs]"]
  node_access_requests[("Access requests")]
  node_recaptcha["reCAPTCHA verification<br/>[recaptcha.cjs]"]
end

subgraph group_description["Description tools"]
  node_description_ui["Description input"]
  node_voice_input["Voice input<br/>[VoiceInput.jsx]"]
  node_correction["Description correction"]
  node_transcription["Transcription API<br/>[transcribe.mjs]"]
end

subgraph group_profiles["Client profiles"]
  node_profiles_hook["Profile state"]
  node_profile_review["Profile review"]
  node_profile_api["Profile handlers"]
  node_profile_rules["Profile rules<br/>[client-profile.mjs]"]
end

node_visitor(("Visitor"))
node_openai["OpenAI services"]

node_visitor -->|"opens calculator"| node_app
node_app -->|"checks access"| node_access_state
node_app -->|"loads profile state"| node_profiles_hook
node_app -->|"shows gate"| node_access_ui
node_app -->|"loads calculator"| node_calculator
node_access_state -->|"provides gate state"| node_access_ui
node_access_ui -.->|"submits access"| node_access_api
node_access_api -->|"checks requests"| node_access_requests
node_access_api -->|"verifies challenge"| node_recaptcha
node_calculator -->|"uses state"| node_estimator
node_estimator -.->|"requests estimate"| node_journey_api
node_journey_api -->|"calculates answers"| node_journey_calc
node_journey_calc -->|"normalizes and calculates"| node_journey_engine
node_journey_engine -->|"calculates base price"| node_base_engine
node_journey_engine -->|"reads pricing"| node_pricing
node_journey_engine -->|"reads rules"| node_commercial
node_journey_calc -->|"validates scope"| node_pricing_bank
node_calculator -->|"renders section"| node_description_ui
node_description_ui -.->|"offers dictation"| node_voice_input
node_voice_input -.->|"sends audio"| node_transcription
node_transcription -->|"transcribes audio"| node_openai
node_estimator -.->|"organizes description"| node_correction
node_profiles_hook -->|"fetches and saves"| node_profile_api
node_profiles_hook -->|"checks profile identity"| node_profile_rules
node_profile_api -->|"validates profile"| node_profile_rules
node_calculator -->|"renders review"| node_profile_review
node_profile_api -->|"requires access"| node_access_api
node_access_api -->|"stores estimates"| node_estimate_records

click node_app "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/App.jsx"
click node_access_ui "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/access/AccessGate.jsx"
click node_access_state "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/access/useAccessGate.js"
click node_access_api "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/api-handlers.mjs"
click node_access_requests "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/access/access-requests.cjs"
click node_recaptcha "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/access/recaptcha.cjs"
click node_calculator "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/calculator/Calculator.jsx"
click node_estimator "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/calculator/useEstimator.js"
click node_pricing "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/approved-pricing.js"
click node_pricing_bank "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/approved-bank.js"
click node_commercial "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/commercial.js"
click node_journey_api "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/api/journey/calculate.mjs"
click node_journey_calc "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/journey-calculation.js"
click node_journey_engine "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/journey-engine.js"
click node_base_engine "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/engine.js"
click node_description_ui "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/calculator/sections/DescriptionSection.jsx"
click node_voice_input "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/description/VoiceInput.jsx"
click node_correction "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/description/description-correction.cjs"
click node_transcription "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/api/intake/transcribe.mjs"
click node_profiles_hook "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/profiles/useClientProfile.js"
click node_profile_review "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/profiles/ClientProfileReview.jsx"
click node_profile_api "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/profiles/client-profiles.mjs"
click node_profile_rules "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/shared/client-profile.mjs"
click node_estimate_records "https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/calculator/estimate-records.cjs"

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_app toneBlue
class node_calculator,node_estimator,node_pricing,node_pricing_bank,node_commercial,node_journey_api,node_journey_calc,node_journey_engine,node_base_engine,node_estimate_records toneAmber
class node_access_ui,node_access_state,node_access_api,node_access_requests,node_recaptcha toneMint
class node_description_ui,node_voice_input,node_correction,node_transcription toneRose
class node_profiles_hook,node_profile_review,node_profile_api,node_profile_rules,node_visitor,node_openai toneIndigo
```

## Components

### Web application

- [App entry](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/App.jsx): `src/App.jsx`

### Estimation

- [Calculator form](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/calculator/Calculator.jsx): `src/features/calculator/Calculator.jsx`
- [Estimator state](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/calculator/useEstimator.js): `src/features/calculator/useEstimator.js`
- [Approved pricing](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/approved-pricing.js): `public/approved-pricing.js`
- [Question bank](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/approved-bank.js): `public/approved-bank.js`
- [Commercial rules](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/commercial.js): `public/commercial.js`
- [Journey API](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/api/journey/calculate.mjs): `api/journey/calculate.mjs`
- [Journey calculation](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/journey-calculation.js): `public/journey-calculation.js`
- [Journey engine](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/journey-engine.js): `public/journey-engine.js`
- [Pricing engine](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/public/engine.js): `public/engine.js`
- [Estimate records](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/calculator/estimate-records.cjs): `server/calculator/estimate-records.cjs`

### Access and intake

- [Access gate UI](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/access/AccessGate.jsx): `src/features/access/AccessGate.jsx`
- [Access state](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/access/useAccessGate.js): `src/features/access/useAccessGate.js`
- [Access handlers](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/api-handlers.mjs): `server/api-handlers.mjs`
- [Access requests](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/access/access-requests.cjs): `server/access/access-requests.cjs`
- [reCAPTCHA verification](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/access/recaptcha.cjs): `server/access/recaptcha.cjs`

### Description tools

- [Description input](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/calculator/sections/DescriptionSection.jsx): `src/features/calculator/sections/DescriptionSection.jsx`
- [Voice input](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/description/VoiceInput.jsx): `src/features/description/VoiceInput.jsx`
- [Description correction](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/description/description-correction.cjs): `server/description/description-correction.cjs`
- [Transcription API](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/api/intake/transcribe.mjs): `api/intake/transcribe.mjs`

### Client profiles

- [Profile state](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/profiles/useClientProfile.js): `src/features/profiles/useClientProfile.js`
- [Profile review](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/src/features/profiles/ClientProfileReview.jsx): `src/features/profiles/ClientProfileReview.jsx`
- [Profile handlers](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/server/profiles/client-profiles.mjs): `server/profiles/client-profiles.mjs`
- [Profile rules](https://github.com/aocgithub/aoc-estimate-calculator-app/blob/main/shared/client-profile.mjs): `shared/client-profile.mjs`

### Other components

- **Visitor**
- **OpenAI services**

## Connections

- Visitor → App entry: opens calculator (evidence: `README.md`)
- App entry → Access state: checks access (evidence: `src/App.jsx`)
- App entry → Profile state: loads profile state (evidence: `src/App.jsx`)
- App entry → Access gate UI: shows gate (evidence: `src/App.jsx`)
- App entry → Calculator form: loads calculator (evidence: `src/App.jsx`)
- Access state → Access gate UI: provides gate state (evidence: `src/App.jsx`)
- Access gate UI → Access handlers: submits access
- Access handlers → Access requests: checks requests (evidence: `server/api-handlers.mjs`)
- Access handlers → reCAPTCHA verification: verifies challenge (evidence: `server/api-handlers.mjs`)
- Calculator form → Estimator state: uses state (evidence: `src/features/calculator/Calculator.jsx`)
- Estimator state → Journey API: requests estimate
- Journey API → Journey calculation: calculates answers
- Journey calculation → Journey engine: normalizes and calculates (evidence: `public/journey-calculation.js`)
- Journey engine → Pricing engine: calculates base price (evidence: `public/journey-engine.js`)
- Journey engine → Approved pricing: reads pricing (evidence: `public/journey-engine.js`)
- Journey engine → Commercial rules: reads rules (evidence: `public/journey-engine.js`)
- Journey calculation → Question bank: validates scope (evidence: `public/journey-calculation.js`)
- Calculator form → Description input: renders section (evidence: `src/features/calculator/Calculator.jsx`)
- Description input → Voice input: offers dictation
- Voice input → Transcription API: sends audio
- Transcription API → OpenAI services: transcribes audio
- Estimator state → Description correction: organizes description
- Profile state → Profile handlers: fetches and saves (evidence: `src/features/profiles/useClientProfile.js`)
- Profile state → Profile rules: checks profile identity (evidence: `src/features/profiles/useClientProfile.js`)
- Profile handlers → Profile rules: validates profile (evidence: `server/profiles/client-profiles.mjs`)
- Calculator form → Profile review: renders review (evidence: `src/features/calculator/Calculator.jsx`)
- Profile handlers → Access handlers: requires access (evidence: `server/profiles/client-profiles.mjs`)
- Access handlers → Estimate records: stores estimates (evidence: `server/api-handlers.mjs`)