# sriram-dee/happiffie architecture

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

- Interactive diagram: https://gitdiagram.com/sriram-dee/happiffie
- Repository: https://github.com/sriram-dee/happiffie

## Overview

Happiffie is an event-vendor marketplace whose main host workflow turns a natural-language or structured request into saved criteria, eligible vendors, scored and ranked recommendations, and invitations. The backend separates parsing, hard eligibility, scoring, and ranking; it can use MongoDB or in-memory data and optionally Gemini. The README documents audit breakdowns and vendor/admin workflows; their detailed API interactions are not fully shown in the excerpts, so those links are documented rather than inferred from co-location.

Main entry points: [`backend/services/matching.service.js`](https://github.com/sriram-dee/happiffie/blob/main/backend/services/matching.service.js) (Matching orchestrator), [`frontend/src/App.jsx`](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/App.jsx) (Marketplace app), [`backend/controllers/requirement.controller.js`](https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/requirement.controller.js) (Requirement API), [`backend/controllers/vendor.controller.js`](https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/vendor.controller.js) (Vendor management API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host matching"]
  node_app["Marketplace app<br/>[App.jsx]"]
  node_requirement_form["Requirement studio"]
  node_recommendation["Recommendations"]
  node_score_audit["Score audit"]
  node_invitations_view["Invitation tracker"]
end

subgraph group_engine["Matching engine"]
  node_gemini["Requirement parsing and rationale<br/>[gemini.service.js]"]
  node_eligibility["Hard eligibility"]
  node_scoring["Seven-factor scoring<br/>[scoring.service.js]"]
  node_ranking["Recommendation ranking<br/>[ranking.service.js]"]
  node_matching["Matching orchestrator"]
end

subgraph group_market["Vendor marketplace"]
  node_vendor_portal["Vendor portal<br/>[VendorPortal.jsx]"]
  node_vendor_auth["Vendor access<br/>[VendorAuthGate.jsx]"]
  node_landing["Marketplace landing<br/>[LandingPage.jsx]"]
end

subgraph group_operations["Vendor and admin operations"]
  node_admin["Admin console<br/>[AdminDashboard.jsx]"]
end

subgraph group_persistence["Persistence and API"]
  node_requirement_controller["Requirement API"]
  node_vendor_controller["Vendor management API"]
  node_invitation_controller["Invitation API"]
  node_api_routes["REST routes<br/>[api.js]"]
  node_vendor_model[("Vendor records<br/>[Vendor.js]")]
  node_requirement_model[("Requirement records<br/>[Requirement.js]")]
  node_match_model[("Match records<br/>[Match.js]")]
  node_invitation_model[("Invitation records<br/>[Invitation.js]")]
  node_db[("MongoDB connection<br/>[db.js]")]
end

node_host_actor(("Event host"))
node_gemini_service{{"Gemini AI"}}
node_admin_actor(("Administrator"))
node_vendor_actor(("Vendor"))

node_host_actor -.->|"uses"| node_app
node_app -->|"renders"| node_requirement_form
node_app -->|"submits request"| node_requirement_controller
node_api_routes -->|"routes to"| node_requirement_controller
node_requirement_controller -->|"parses with"| node_gemini
node_requirement_controller -->|"saves"| node_requirement_model
node_requirement_controller -->|"starts matching"| node_matching
node_matching -->|"loads vendors"| node_vendor_model
node_matching -->|"filters"| node_eligibility
node_matching -->|"scores eligible"| node_scoring
node_matching -->|"ranks pool"| node_ranking
node_matching -->|"explains matches"| node_gemini
node_matching -->|"saves matches"| node_match_model
node_gemini -.->|"calls optionally"| node_gemini_service
node_app -->|"renders"| node_recommendation
node_app -->|"renders"| node_score_audit
node_app -->|"renders"| node_invitations_view
node_recommendation -.->|"opens audit"| node_score_audit
node_recommendation -.->|"invites vendor"| node_invitation_controller
node_api_routes -->|"routes vendor calls"| node_vendor_controller
node_api_routes -->|"routes invitations"| node_invitation_controller
node_invitation_controller -->|"reads and writes"| node_invitation_model
node_vendor_controller -->|"reads and updates"| node_vendor_model
node_vendor_controller -->|"checks connection"| node_db
node_vendor_controller -.->|"uses seed data"| node_vendor_model
node_vendor_actor -.->|"uses"| node_vendor_portal
node_vendor_portal -.->|"authenticates through"| node_vendor_auth
node_vendor_portal -.->|"responds to invitations"| node_invitation_controller
node_admin_actor -.->|"uses"| node_admin
node_admin -.->|"manages vendors"| node_vendor_controller
node_admin -.->|"inspects matches"| node_match_model

click node_app "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/App.jsx"
click node_requirement_form "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/RequirementForm.jsx"
click node_recommendation "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/RecommendationCard.jsx"
click node_score_audit "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/ScoreBreakdownModal.jsx"
click node_invitations_view "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/InvitationsView.jsx"
click node_gemini "https://github.com/sriram-dee/happiffie/blob/main/backend/services/gemini.service.js"
click node_eligibility "https://github.com/sriram-dee/happiffie/blob/main/backend/services/eligibility.service.js"
click node_scoring "https://github.com/sriram-dee/happiffie/blob/main/backend/services/scoring.service.js"
click node_ranking "https://github.com/sriram-dee/happiffie/blob/main/backend/services/ranking.service.js"
click node_matching "https://github.com/sriram-dee/happiffie/blob/main/backend/services/matching.service.js"
click node_vendor_portal "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/VendorPortal.jsx"
click node_vendor_auth "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/VendorAuthGate.jsx"
click node_landing "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/LandingPage.jsx"
click node_admin "https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/AdminDashboard.jsx"
click node_requirement_controller "https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/requirement.controller.js"
click node_vendor_controller "https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/vendor.controller.js"
click node_invitation_controller "https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/invitation.controller.js"
click node_api_routes "https://github.com/sriram-dee/happiffie/blob/main/backend/routes/api.js"
click node_vendor_model "https://github.com/sriram-dee/happiffie/blob/main/backend/models/Vendor.js"
click node_requirement_model "https://github.com/sriram-dee/happiffie/blob/main/backend/models/Requirement.js"
click node_match_model "https://github.com/sriram-dee/happiffie/blob/main/backend/models/Match.js"
click node_invitation_model "https://github.com/sriram-dee/happiffie/blob/main/backend/models/Invitation.js"
click node_db "https://github.com/sriram-dee/happiffie/blob/main/backend/config/db.js"

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_requirement_form,node_recommendation,node_score_audit,node_invitations_view toneBlue
class node_gemini,node_eligibility,node_scoring,node_ranking,node_matching toneAmber
class node_vendor_portal,node_vendor_auth,node_landing toneMint
class node_admin toneRose
class node_requirement_controller,node_vendor_controller,node_invitation_controller,node_api_routes,node_vendor_model,node_requirement_model,node_match_model,node_invitation_model,node_db,node_host_actor,node_gemini_service,node_admin_actor,node_vendor_actor toneIndigo
```

## Components

### Host matching

- [Marketplace app](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Requirement studio](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/RequirementForm.jsx): `frontend/src/components/RequirementForm.jsx`
- [Recommendations](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/RecommendationCard.jsx): `frontend/src/components/RecommendationCard.jsx`
- [Score audit](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/ScoreBreakdownModal.jsx): `frontend/src/components/ScoreBreakdownModal.jsx`
- [Invitation tracker](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/InvitationsView.jsx): `frontend/src/components/InvitationsView.jsx`

### Matching engine

- [Requirement parsing and rationale](https://github.com/sriram-dee/happiffie/blob/main/backend/services/gemini.service.js): `backend/services/gemini.service.js`
- [Hard eligibility](https://github.com/sriram-dee/happiffie/blob/main/backend/services/eligibility.service.js): `backend/services/eligibility.service.js`
- [Seven-factor scoring](https://github.com/sriram-dee/happiffie/blob/main/backend/services/scoring.service.js): `backend/services/scoring.service.js`
- [Recommendation ranking](https://github.com/sriram-dee/happiffie/blob/main/backend/services/ranking.service.js): `backend/services/ranking.service.js`
- [Matching orchestrator](https://github.com/sriram-dee/happiffie/blob/main/backend/services/matching.service.js): `backend/services/matching.service.js`

### Vendor marketplace

- [Vendor portal](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/VendorPortal.jsx): `frontend/src/components/VendorPortal.jsx`
- [Vendor access](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/VendorAuthGate.jsx): `frontend/src/components/VendorAuthGate.jsx`
- [Marketplace landing](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/LandingPage.jsx): `frontend/src/components/LandingPage.jsx`

### Vendor and admin operations

- [Admin console](https://github.com/sriram-dee/happiffie/blob/main/frontend/src/components/AdminDashboard.jsx): `frontend/src/components/AdminDashboard.jsx`

### Persistence and API

- [Requirement API](https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/requirement.controller.js): `backend/controllers/requirement.controller.js`
- [Vendor management API](https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/vendor.controller.js): `backend/controllers/vendor.controller.js`
- [Invitation API](https://github.com/sriram-dee/happiffie/blob/main/backend/controllers/invitation.controller.js): `backend/controllers/invitation.controller.js`
- [REST routes](https://github.com/sriram-dee/happiffie/blob/main/backend/routes/api.js): `backend/routes/api.js`
- [Vendor records](https://github.com/sriram-dee/happiffie/blob/main/backend/models/Vendor.js): `backend/models/Vendor.js`
- [Requirement records](https://github.com/sriram-dee/happiffie/blob/main/backend/models/Requirement.js): `backend/models/Requirement.js`
- [Match records](https://github.com/sriram-dee/happiffie/blob/main/backend/models/Match.js): `backend/models/Match.js`
- [Invitation records](https://github.com/sriram-dee/happiffie/blob/main/backend/models/Invitation.js): `backend/models/Invitation.js`
- [MongoDB connection](https://github.com/sriram-dee/happiffie/blob/main/backend/config/db.js): `backend/config/db.js`

### Other components

- **Event host**
- **Gemini AI**
- **Administrator**
- **Vendor**

## Connections

- Event host → Marketplace app: uses (evidence: `README.md`)
- Marketplace app → Requirement studio: renders (evidence: `frontend/src/App.jsx`)
- Marketplace app → Requirement API: submits request (evidence: `frontend/src/App.jsx`)
- REST routes → Requirement API: routes to (evidence: `backend/routes/api.js`)
- Requirement API → Requirement parsing and rationale: parses with (evidence: `backend/controllers/requirement.controller.js`)
- Requirement API → Requirement records: saves (evidence: `backend/controllers/requirement.controller.js`)
- Requirement API → Matching orchestrator: starts matching (evidence: `backend/controllers/requirement.controller.js`)
- Matching orchestrator → Vendor records: loads vendors (evidence: `backend/services/matching.service.js`)
- Matching orchestrator → Hard eligibility: filters (evidence: `backend/services/matching.service.js`)
- Matching orchestrator → Seven-factor scoring: scores eligible (evidence: `backend/services/matching.service.js`)
- Matching orchestrator → Recommendation ranking: ranks pool (evidence: `backend/services/matching.service.js`)
- Matching orchestrator → Requirement parsing and rationale: explains matches (evidence: `backend/services/matching.service.js`)
- Matching orchestrator → Match records: saves matches (evidence: `backend/services/matching.service.js`)
- Requirement parsing and rationale → Gemini AI: calls optionally (evidence: `README.md`)
- Marketplace app → Recommendations: renders (evidence: `frontend/src/App.jsx`)
- Marketplace app → Score audit: renders (evidence: `frontend/src/App.jsx`)
- Marketplace app → Invitation tracker: renders (evidence: `frontend/src/App.jsx`)
- Recommendations → Score audit: opens audit (evidence: `README.md`)
- Recommendations → Invitation API: invites vendor (evidence: `README.md`)
- REST routes → Vendor management API: routes vendor calls (evidence: `backend/routes/api.js`)
- REST routes → Invitation API: routes invitations (evidence: `backend/routes/api.js`)
- Invitation API → Invitation records: reads and writes (evidence: `backend/controllers/invitation.controller.js`)
- Vendor management API → Vendor records: reads and updates (evidence: `backend/controllers/vendor.controller.js`)
- Vendor management API → MongoDB connection: checks connection (evidence: `backend/controllers/vendor.controller.js`)
- Vendor management API → Vendor records: uses seed data (evidence: `backend/controllers/vendor.controller.js`)
- Vendor → Vendor portal: uses (evidence: `README.md`)
- Vendor portal → Vendor access: authenticates through (evidence: `frontend/src/components/VendorPortal.jsx`)
- Vendor portal → Invitation API: responds to invitations (evidence: `README.md`)
- Administrator → Admin console: uses (evidence: `README.md`)
- Admin console → Vendor management API: manages vendors (evidence: `README.md`)
- Admin console → Match records: inspects matches (evidence: `README.md`)
