# baitc-hacks/hack-4a3a9b1c-vibeops architecture

> Architecture diagram of the GitHub repository baitc-hacks/hack-4a3a9b1c-vibeops, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baitc-hacks/hack-4a3a9b1c-vibeops
- Repository: https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops

## Overview

Firebird is an event-contractor recommendation assistant. Its main workflow gathers and confirms event requirements, filters and ranks the vendor catalog, then returns up to three evidence-backed recommendations; users can also request preference comparisons or apply date/budget alternatives. The README documents the full workflow, while the sampled source confirms key UI, API, assistant, catalog, and decision-support responsibilities; unsampled orchestration links are included only where documented.

Main entry points: [`client/src/App.tsx`](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/App.tsx) (Search workspace), [`server/recommend.ts`](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/recommend.ts) (Recommendation flow), [`server/explanations/assistant-brief.ts`](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/assistant-brief.ts) (Requirement extraction), [`client/src/api.ts`](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User experience"]
  node_app["Search workspace<br/>[App.tsx]"]
  node_assistant_ui["Requirements dialog<br/>[Assistant.tsx]"]
  node_decision_ui["Alternative controls"]
  node_client_api["API client<br/>[api.ts]"]
end

subgraph group_server["Request workflow"]
  node_http["Express API<br/>[app.ts]"]
  node_recommend["Recommendation flow<br/>[recommend.ts]"]
  node_validation["Query validation<br/>[validation.ts]"]
end

subgraph group_catalog["Catalog selection"]
  node_catalog[("Vendor catalog<br/>[catalog.ts]")]
  node_vendor_data["Vendor CSV<br/>[vendors.csv]"]
  node_matching["Filter and rank<br/>[matching.ts]"]
  node_alternatives["Date and budget options<br/>[alternatives.ts]"]
end

subgraph group_ai["AI and evidence"]
  node_brief["Requirement extraction<br/>[assistant-brief.ts]"]
  node_compare["Preference comparison"]
  node_explanations["Evidence explanations<br/>[index.ts]"]
  node_evidence["Quote verification<br/>[evidence.ts]"]
  node_provider["Model adapter<br/>[provider.ts]"]
  node_exchange["Exchange rates<br/>[exchange-rates.ts]"]
end

node_user(("Event planner"))
node_openai{{"OpenAI Responses API"}}

node_user -->|"describes event"| node_assistant_ui
node_assistant_ui -->|"requests brief"| node_client_api
node_app -->|"requests search"| node_client_api
node_client_api -->|"sends API request"| node_http
node_http -->|"dispatches brief"| node_brief
node_brief -->|"reads options"| node_catalog
node_brief -->|"validates draft"| node_validation
node_brief -->|"converts currency"| node_exchange
node_brief -->|"requests extraction"| node_openai
node_brief -->|"returns draft"| node_assistant_ui
node_user -->|"confirms conditions"| node_app
node_http -->|"dispatches search"| node_recommend
node_recommend -->|"validates query"| node_validation
node_recommend -->|"uses vendor data"| node_catalog
node_catalog -->|"loads records"| node_vendor_data
node_recommend -->|"selects candidates"| node_matching
node_recommend -->|"builds explanations"| node_explanations
node_explanations -->|"requests evidence"| node_provider
node_provider -->|"requests quotes"| node_openai
node_explanations -->|"verifies quotes"| node_evidence
node_recommend -->|"computes alternatives"| node_alternatives
node_alternatives -->|"tests conditions"| node_matching
node_http -->|"dispatches comparison"| node_compare
node_compare -->|"validates query"| node_validation
node_compare -->|"selects candidates"| node_matching
node_compare -->|"requests comparison"| node_openai
node_http -->|"returns results"| node_client_api
node_client_api -->|"provides results"| node_app
node_app -->|"shows alternatives"| node_decision_ui
node_app -->|"requests comparison"| node_client_api
node_decision_ui -->|"applies alternative"| node_app
node_app -->|"shows recommendations"| node_user

click node_app "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/App.tsx"
click node_assistant_ui "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/Assistant.tsx"
click node_decision_ui "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/DecisionSupport.tsx"
click node_client_api "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/api.ts"
click node_http "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/app.ts"
click node_recommend "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/recommend.ts"
click node_validation "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/validation.ts"
click node_catalog "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/catalog.ts"
click node_vendor_data "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/data/vendors.csv"
click node_matching "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/matching.ts"
click node_alternatives "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/alternatives.ts"
click node_brief "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/assistant-brief.ts"
click node_compare "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/assistant-compare.ts"
click node_explanations "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/index.ts"
click node_evidence "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/evidence.ts"
click node_provider "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/provider.ts"
click node_exchange "https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/exchange-rates.ts"

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,node_assistant_ui,node_decision_ui,node_client_api toneBlue
class node_http,node_recommend,node_validation toneAmber
class node_catalog,node_vendor_data,node_matching,node_alternatives,node_openai toneMint
class node_brief,node_compare,node_explanations,node_evidence,node_provider,node_exchange toneRose
class node_user toneIndigo
```

## Components

### User experience

- [Search workspace](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Requirements dialog](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/Assistant.tsx): `client/src/Assistant.tsx`
- [Alternative controls](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/DecisionSupport.tsx): `client/src/DecisionSupport.tsx`
- [API client](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/client/src/api.ts): `client/src/api.ts`

### Request workflow

- [Express API](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/app.ts): `server/app.ts`
- [Recommendation flow](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/recommend.ts): `server/recommend.ts`
- [Query validation](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/validation.ts): `server/validation.ts`

### Catalog selection

- [Vendor catalog](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/catalog.ts): `server/catalog.ts`
- [Vendor CSV](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/data/vendors.csv): `data/vendors.csv`
- [Filter and rank](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/matching.ts): `server/matching.ts`
- [Date and budget options](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/alternatives.ts): `server/alternatives.ts`

### AI and evidence

- [Requirement extraction](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/assistant-brief.ts): `server/explanations/assistant-brief.ts`
- [Preference comparison](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/assistant-compare.ts): `server/explanations/assistant-compare.ts`
- [Evidence explanations](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/index.ts): `server/explanations/index.ts`
- [Quote verification](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/evidence.ts): `server/explanations/evidence.ts`
- [Model adapter](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/provider.ts): `server/explanations/provider.ts`
- [Exchange rates](https://github.com/baitc-hacks/hack-4a3a9b1c-vibeops/blob/main/server/explanations/exchange-rates.ts): `server/explanations/exchange-rates.ts`

### Other components

- **Event planner**
- **OpenAI Responses API**

## Connections

- Event planner → Requirements dialog: describes event
- Requirements dialog → API client: requests brief
- Search workspace → API client: requests search
- API client → Express API: sends API request
- Express API → Requirement extraction: dispatches brief
- Requirement extraction → Vendor catalog: reads options
- Requirement extraction → Query validation: validates draft
- Requirement extraction → Exchange rates: converts currency
- Requirement extraction → OpenAI Responses API: requests extraction
- Requirement extraction → Requirements dialog: returns draft
- Event planner → Search workspace: confirms conditions
- Express API → Recommendation flow: dispatches search
- Recommendation flow → Query validation: validates query
- Recommendation flow → Vendor catalog: uses vendor data
- Vendor catalog → Vendor CSV: loads records
- Recommendation flow → Filter and rank: selects candidates
- Recommendation flow → Evidence explanations: builds explanations
- Evidence explanations → Model adapter: requests evidence
- Model adapter → OpenAI Responses API: requests quotes
- Evidence explanations → Quote verification: verifies quotes
- Recommendation flow → Date and budget options: computes alternatives
- Date and budget options → Filter and rank: tests conditions
- Express API → Preference comparison: dispatches comparison
- Preference comparison → Query validation: validates query
- Preference comparison → Filter and rank: selects candidates
- Preference comparison → OpenAI Responses API: requests comparison
- Express API → API client: returns results
- API client → Search workspace: provides results
- Search workspace → Alternative controls: shows alternatives
- Search workspace → API client: requests comparison
- Alternative controls → Search workspace: applies alternative
- Search workspace → Event planner: shows recommendations