# ganeshkumart3095-cyber/samaroh architecture

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

- Interactive diagram: https://gitdiagram.com/ganeshkumart3095-cyber/samaroh
- Repository: https://github.com/ganeshkumart3095-cyber/samaroh

## Overview

Samaroh is a multilingual planner for Indian celebrations. A person enters an event brief through the wizard or asks for a plan; the plan API validates the request, obtains an AI blueprint or curated fallback, and assembles a deterministic plan. The dashboard then supports budget, timeline, vendors, guests, ideas, assistant-driven changes, sharing, and calendar export, with plans saved locally and optionally mirrored to Firestore. README capabilities such as regional calendar checks, grounded ideas, and Google Calendar sync are represented where the tree supports them; unsampled implementations are not assumed to have specific call paths.

Main entry points: [`src/ui/dashboard/Dashboard.tsx`](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ui/dashboard/Dashboard.tsx) (Plan dashboard), [`src/app/api/plan/route.ts`](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/plan/route.ts) (Plan API), [`src/ai/provider.ts`](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ai/provider.ts) (AI provider selection), [`src/core/assemble.ts`](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/assemble.ts) (Plan assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Planning experience"]
  node_wizard["Brief wizard<br/>[Wizard.tsx]"]
  node_dashboard["Plan dashboard<br/>[Dashboard.tsx]"]
  node_planview["Plan detail route<br/>[page.tsx]"]
  node_localization["Four-language UI<br/>[index.ts]"]
  node_browserapi["Browser API client<br/>[api.ts]"]
end

subgraph group_planning["Plan generation"]
  node_planapi["Plan API<br/>[route.ts]"]
  node_ideasapi["Ideas API<br/>[route.ts]"]
  node_briefapi["Brief API<br/>[route.ts]"]
  node_template["Curated templates<br/>[templates.ts]"]
end

subgraph group_assistant["AI and ideas"]
  node_assistantapi["Assistant API<br/>[route.ts]"]
  node_assistantengine["Assistant engine<br/>[assistant.ts]"]
  node_provider["AI provider selection<br/>[provider.ts]"]
  node_ideas["Grounded ideas<br/>[gemini.ts]"]
end

subgraph group_domain["Event domain"]
  node_assemble["Plan assembly<br/>[assemble.ts]"]
  node_calendar["Calendar rules<br/>[calendar.ts]"]
  node_schedule["Schedule logic<br/>[schedule.ts]"]
  node_presets["Event presets<br/>[presets.ts]"]
  node_changes["Plan mutations<br/>[changes.ts]"]
  node_money["Rupee allocation<br/>[money.ts]"]
  node_ics["Calendar export<br/>[ics.ts]"]
end

subgraph group_state["Persistence and services"]
  node_localstore[("Local plan store<br/>[local.ts]")]
  node_cloudstore["Cloud plan sync<br/>[cloud.ts]"]
  node_firestore[("Firestore<br/>[firebase.ts]")]
  node_guard["Request validation<br/>[guard.ts]"]
end

node_person(("Event planner"))

node_person -->|"enters brief"| node_wizard
node_wizard -.->|"requests plan"| node_browserapi
node_browserapi -.->|"POSTs brief"| node_planapi
node_person -.->|"opens plan"| node_planview
node_planview -->|"renders"| node_dashboard
node_dashboard -->|"loads and saves"| node_localstore
node_dashboard -.->|"requests refresh"| node_browserapi
node_dashboard -->|"applies changes"| node_changes
node_dashboard -->|"exports calendar"| node_ics
node_dashboard -.->|"asks assistant"| node_assistantapi
node_dashboard -->|"translates UI"| node_localization
node_planapi -->|"validates request"| node_guard
node_planapi -->|"selects model"| node_provider
node_planapi -->|"falls back"| node_template
node_planapi -->|"assembles plan"| node_assemble
node_assemble -->|"uses defaults"| node_presets
node_assemble -->|"builds schedule"| node_schedule
node_template -->|"uses function defaults"| node_presets
node_briefapi -->|"selects model"| node_provider
node_briefapi -->|"uses trusted date"| node_schedule
node_ideasapi -->|"requests ideas"| node_provider
node_ideasapi -->|"uses fallback ideas"| node_template
node_assistantapi -->|"selects model"| node_provider
node_provider -->|"creates assistant"| node_assistantengine
node_assistantengine -->|"proposes mutations"| node_changes
node_assistantengine -.->|"grounds ideas"| node_ideas
node_ideasapi -.->|"uses grounding"| node_ideas
node_localstore -->|"mirrors changes"| node_cloudstore
node_cloudstore -.->|"persists remotely"| node_firestore
node_dashboard -.->|"calendar constraints"| node_calendar
node_assemble -.->|"allocates budget"| node_money

click node_wizard "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ui/wizard/Wizard.tsx"
click node_dashboard "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ui/dashboard/Dashboard.tsx"
click node_planview "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/plan/%5Bid%5D/page.tsx"
click node_localization "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/i18n/index.ts"
click node_planapi "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/plan/route.ts"
click node_ideasapi "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/ideas/route.ts"
click node_briefapi "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/brief/route.ts"
click node_template "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/templates.ts"
click node_assemble "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/assemble.ts"
click node_calendar "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/calendar.ts"
click node_schedule "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/schedule.ts"
click node_presets "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/presets.ts"
click node_changes "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/changes.ts"
click node_money "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/money.ts"
click node_ics "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/ics.ts"
click node_assistantapi "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/assistant/route.ts"
click node_assistantengine "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ai/assistant.ts"
click node_provider "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ai/provider.ts"
click node_ideas "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ai/gemini.ts"
click node_browserapi "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ui/api.ts"
click node_localstore "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/store/local.ts"
click node_cloudstore "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/store/cloud.ts"
click node_firestore "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/store/firebase.ts"
click node_guard "https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/server/guard.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_wizard,node_dashboard,node_planview,node_localization,node_browserapi toneBlue
class node_planapi,node_ideasapi,node_briefapi,node_template toneAmber
class node_assistantapi,node_assistantengine,node_provider,node_ideas toneMint
class node_assemble,node_calendar,node_schedule,node_presets,node_changes,node_money,node_ics toneRose
class node_localstore,node_cloudstore,node_firestore,node_guard,node_person toneIndigo
```

## Components

### Planning experience

- [Brief wizard](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ui/wizard/Wizard.tsx): `src/ui/wizard/Wizard.tsx`
- [Plan dashboard](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ui/dashboard/Dashboard.tsx): `src/ui/dashboard/Dashboard.tsx`
- [Plan detail route](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/plan/%5Bid%5D/page.tsx): `src/app/plan/[id]/page.tsx`
- [Four-language UI](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/i18n/index.ts): `src/i18n/index.ts`
- [Browser API client](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ui/api.ts): `src/ui/api.ts`

### Plan generation

- [Plan API](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/plan/route.ts): `src/app/api/plan/route.ts`
- [Ideas API](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/ideas/route.ts): `src/app/api/ideas/route.ts`
- [Brief API](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/brief/route.ts): `src/app/api/brief/route.ts`
- [Curated templates](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/templates.ts): `src/core/templates.ts`

### AI and ideas

- [Assistant API](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/app/api/assistant/route.ts): `src/app/api/assistant/route.ts`
- [Assistant engine](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ai/assistant.ts): `src/ai/assistant.ts`
- [AI provider selection](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ai/provider.ts): `src/ai/provider.ts`
- [Grounded ideas](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/ai/gemini.ts): `src/ai/gemini.ts`

### Event domain

- [Plan assembly](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/assemble.ts): `src/core/assemble.ts`
- [Calendar rules](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/calendar.ts): `src/core/calendar.ts`
- [Schedule logic](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/schedule.ts): `src/core/schedule.ts`
- [Event presets](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/presets.ts): `src/core/presets.ts`
- [Plan mutations](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/changes.ts): `src/core/changes.ts`
- [Rupee allocation](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/money.ts): `src/core/money.ts`
- [Calendar export](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/core/ics.ts): `src/core/ics.ts`

### Persistence and services

- [Local plan store](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/store/local.ts): `src/store/local.ts`
- [Cloud plan sync](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/store/cloud.ts): `src/store/cloud.ts`
- [Firestore](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/store/firebase.ts): `src/store/firebase.ts`
- [Request validation](https://github.com/ganeshkumart3095-cyber/samaroh/blob/main/src/server/guard.ts): `src/server/guard.ts`

### Other components

- **Event planner**

## Connections

- Event planner → Brief wizard: enters brief (evidence: `src/ui/wizard/Wizard.tsx`)
- Brief wizard → Browser API client: requests plan (evidence: `src/ui/wizard/Wizard.tsx`)
- Browser API client → Plan API: POSTs brief
- Event planner → Plan detail route: opens plan
- Plan detail route → Plan dashboard: renders (evidence: `src/app/plan/[id]/page.tsx`)
- Plan dashboard → Local plan store: loads and saves (evidence: `src/ui/dashboard/Dashboard.tsx`)
- Plan dashboard → Browser API client: requests refresh (evidence: `src/ui/dashboard/Dashboard.tsx`)
- Plan dashboard → Plan mutations: applies changes (evidence: `src/ui/dashboard/Dashboard.tsx`)
- Plan dashboard → Calendar export: exports calendar (evidence: `src/ui/dashboard/Dashboard.tsx`)
- Plan dashboard → Assistant API: asks assistant
- Plan dashboard → Four-language UI: translates UI (evidence: `src/ui/dashboard/Dashboard.tsx`)
- Plan API → Request validation: validates request (evidence: `src/app/api/plan/route.ts`)
- Plan API → AI provider selection: selects model (evidence: `src/app/api/plan/route.ts`)
- Plan API → Curated templates: falls back (evidence: `src/app/api/plan/route.ts`)
- Plan API → Plan assembly: assembles plan (evidence: `src/app/api/plan/route.ts`)
- Plan assembly → Event presets: uses defaults (evidence: `src/core/assemble.ts`)
- Plan assembly → Schedule logic: builds schedule (evidence: `src/core/assemble.ts`)
- Curated templates → Event presets: uses function defaults (evidence: `src/core/templates.ts`)
- Brief API → AI provider selection: selects model (evidence: `src/app/api/brief/route.ts`)
- Brief API → Schedule logic: uses trusted date (evidence: `src/app/api/brief/route.ts`)
- Ideas API → AI provider selection: requests ideas (evidence: `src/app/api/ideas/route.ts`)
- Ideas API → Curated templates: uses fallback ideas (evidence: `src/app/api/ideas/route.ts`)
- Assistant API → AI provider selection: selects model (evidence: `src/app/api/assistant/route.ts`)
- AI provider selection → Assistant engine: creates assistant (evidence: `src/ai/provider.ts`)
- Assistant engine → Plan mutations: proposes mutations (evidence: `src/ai/assistant.ts`)
- Assistant engine → Grounded ideas: grounds ideas
- Ideas API → Grounded ideas: uses grounding
- Local plan store → Cloud plan sync: mirrors changes (evidence: `src/store/local.ts`)
- Cloud plan sync → Firestore: persists remotely (evidence: `src/store/cloud.ts`)
- Plan dashboard → Calendar rules: calendar constraints
- Plan assembly → Rupee allocation: allocates budget