# nithyasahasra/business-idea-validator architecture

> Architecture diagram of the GitHub repository nithyasahasra/business-idea-validator, 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/nithyasahasra/business-idea-validator
- Repository: https://github.com/nithyasahasra/business-idea-validator

## Overview

IdeaLens is a full-stack business-idea validation platform. A user signs in, submits an idea, and follows a queued research job through six stages to a persistent, source-linked report and deterministic opportunity score. The graph includes the documented authentication, report browsing, and email-verification capabilities. The README describes several subsystems whose implementation was not sampled; those links are documented rather than inferred from unseen code.

Main entry points: [`App.jsx`](https://github.com/nithyasahasra/business-idea-validator/blob/main/App.jsx) (React app), [`research_service.py`](https://github.com/nithyasahasra/business-idea-validator/blob/main/research_service.py) (Research stages), [`main.py`](https://github.com/nithyasahasra/business-idea-validator/blob/main/main.py) (FastAPI app), [`api.js`](https://github.com/nithyasahasra/business-idea-validator/blob/main/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web application"]
  node_app["React app<br/>[App.jsx]"]
  node_auth_ui["Sign-in and signup<br/>[SignIn.jsx]"]
  node_verify_ui["Email verification<br/>[VerifyEmail.jsx]"]
  node_validate_ui["Idea submission<br/>[Validate.jsx]"]
  node_research_ui["Job progress<br/>[Research.jsx]"]
  node_reports_ui["Report history<br/>[MyReports.jsx]"]
  node_report_ui["Validation report<br/>[Report.jsx]"]
  node_auth_context["Auth state<br/>[AuthContext.jsx]"]
  node_api_client["API client<br/>[api.js]"]
end

subgraph group_api["API and identity"]
  node_api_server["FastAPI app<br/>[main.py]"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_auth_service["Auth service<br/>[auth_service.py]"]
  node_email_service["Email delivery<br/>[email_service.py]"]
  node_idea_routes["Idea routes<br/>[ideas.py]"]
  node_research_routes["Research routes<br/>[research.py]"]
  node_report_routes["Report routes<br/>[reports.py]"]
end

subgraph group_research["Research pipeline"]
  node_worker["Research worker<br/>[worker.py]"]
  node_pipeline["Research stages"]
  node_search["Evidence search<br/>[search_service.py]"]
  node_llm["Report synthesis<br/>[llm_service.py]"]
  node_scoring["Opportunity scoring<br/>[scoring_service.py]"]
end

subgraph group_persistence["Persistence"]
  node_database[("Application database<br/>[database.py]")]
end

node_user(("Founder"))
node_tavily["Tavily Search"]
node_openai["OpenAI"]
node_resend["Resend email"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_auth_ui
node_app -->|"routes to"| node_verify_ui
node_app -->|"routes to"| node_validate_ui
node_app -->|"routes to"| node_research_ui
node_app -->|"routes to"| node_reports_ui
node_app -->|"routes to"| node_report_ui
node_user -->|"submits idea"| node_validate_ui
node_auth_ui -.->|"uses auth"| node_auth_context
node_validate_ui -.->|"submits via"| node_api_client
node_research_ui -.->|"polls via"| node_api_client
node_reports_ui -.->|"fetches via"| node_api_client
node_report_ui -.->|"fetches via"| node_api_client
node_api_client -->|"HTTP JSON"| node_api_server
node_api_server -->|"registers"| node_auth_routes
node_api_server -->|"registers"| node_idea_routes
node_api_server -->|"registers"| node_research_routes
node_api_server -->|"registers"| node_report_routes
node_auth_routes -.->|"delegates to"| node_auth_service
node_auth_routes -.->|"sends email"| node_email_service
node_email_service -->|"sends via"| node_resend
node_idea_routes -->|"queues job"| node_database
node_worker -->|"claims jobs"| node_database
node_worker -->|"processes job"| node_pipeline
node_pipeline -->|"collects evidence"| node_search
node_search -->|"searches"| node_tavily
node_pipeline -->|"persists sources"| node_database
node_pipeline -->|"synthesizes report"| node_llm
node_llm -->|"generates report"| node_openai
node_pipeline -->|"calculates score"| node_scoring
node_pipeline -->|"persists report"| node_database
node_report_routes -.->|"reads reports"| node_database

click node_app "https://github.com/nithyasahasra/business-idea-validator/blob/main/App.jsx"
click node_auth_ui "https://github.com/nithyasahasra/business-idea-validator/blob/main/SignIn.jsx"
click node_verify_ui "https://github.com/nithyasahasra/business-idea-validator/blob/main/VerifyEmail.jsx"
click node_validate_ui "https://github.com/nithyasahasra/business-idea-validator/blob/main/Validate.jsx"
click node_research_ui "https://github.com/nithyasahasra/business-idea-validator/blob/main/Research.jsx"
click node_reports_ui "https://github.com/nithyasahasra/business-idea-validator/blob/main/MyReports.jsx"
click node_report_ui "https://github.com/nithyasahasra/business-idea-validator/blob/main/Report.jsx"
click node_auth_context "https://github.com/nithyasahasra/business-idea-validator/blob/main/AuthContext.jsx"
click node_api_client "https://github.com/nithyasahasra/business-idea-validator/blob/main/api.js"
click node_api_server "https://github.com/nithyasahasra/business-idea-validator/blob/main/main.py"
click node_auth_routes "https://github.com/nithyasahasra/business-idea-validator/blob/main/auth.py"
click node_auth_service "https://github.com/nithyasahasra/business-idea-validator/blob/main/auth_service.py"
click node_email_service "https://github.com/nithyasahasra/business-idea-validator/blob/main/email_service.py"
click node_idea_routes "https://github.com/nithyasahasra/business-idea-validator/blob/main/ideas.py"
click node_research_routes "https://github.com/nithyasahasra/business-idea-validator/blob/main/research.py"
click node_report_routes "https://github.com/nithyasahasra/business-idea-validator/blob/main/reports.py"
click node_worker "https://github.com/nithyasahasra/business-idea-validator/blob/main/worker.py"
click node_pipeline "https://github.com/nithyasahasra/business-idea-validator/blob/main/research_service.py"
click node_search "https://github.com/nithyasahasra/business-idea-validator/blob/main/search_service.py"
click node_llm "https://github.com/nithyasahasra/business-idea-validator/blob/main/llm_service.py"
click node_scoring "https://github.com/nithyasahasra/business-idea-validator/blob/main/scoring_service.py"
click node_database "https://github.com/nithyasahasra/business-idea-validator/blob/main/database.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_app,node_auth_ui,node_verify_ui,node_validate_ui,node_research_ui,node_reports_ui,node_report_ui,node_auth_context,node_api_client toneBlue
class node_api_server,node_auth_routes,node_auth_service,node_email_service,node_idea_routes,node_research_routes,node_report_routes toneAmber
class node_worker,node_pipeline,node_search,node_llm,node_scoring toneMint
class node_database toneRose
class node_user,node_tavily,node_openai,node_resend toneIndigo
```

## Components

### Web application

- [React app](https://github.com/nithyasahasra/business-idea-validator/blob/main/App.jsx): `App.jsx`
- [Sign-in and signup](https://github.com/nithyasahasra/business-idea-validator/blob/main/SignIn.jsx): `SignIn.jsx`
- [Email verification](https://github.com/nithyasahasra/business-idea-validator/blob/main/VerifyEmail.jsx): `VerifyEmail.jsx`
- [Idea submission](https://github.com/nithyasahasra/business-idea-validator/blob/main/Validate.jsx): `Validate.jsx`
- [Job progress](https://github.com/nithyasahasra/business-idea-validator/blob/main/Research.jsx): `Research.jsx`
- [Report history](https://github.com/nithyasahasra/business-idea-validator/blob/main/MyReports.jsx): `MyReports.jsx`
- [Validation report](https://github.com/nithyasahasra/business-idea-validator/blob/main/Report.jsx): `Report.jsx`
- [Auth state](https://github.com/nithyasahasra/business-idea-validator/blob/main/AuthContext.jsx): `AuthContext.jsx`
- [API client](https://github.com/nithyasahasra/business-idea-validator/blob/main/api.js): `api.js`

### API and identity

- [FastAPI app](https://github.com/nithyasahasra/business-idea-validator/blob/main/main.py): `main.py`
- [Auth routes](https://github.com/nithyasahasra/business-idea-validator/blob/main/auth.py): `auth.py`
- [Auth service](https://github.com/nithyasahasra/business-idea-validator/blob/main/auth_service.py): `auth_service.py`
- [Email delivery](https://github.com/nithyasahasra/business-idea-validator/blob/main/email_service.py): `email_service.py`
- [Idea routes](https://github.com/nithyasahasra/business-idea-validator/blob/main/ideas.py): `ideas.py`
- [Research routes](https://github.com/nithyasahasra/business-idea-validator/blob/main/research.py): `research.py`
- [Report routes](https://github.com/nithyasahasra/business-idea-validator/blob/main/reports.py): `reports.py`

### Research pipeline

- [Research worker](https://github.com/nithyasahasra/business-idea-validator/blob/main/worker.py): `worker.py`
- [Research stages](https://github.com/nithyasahasra/business-idea-validator/blob/main/research_service.py): `research_service.py`
- [Evidence search](https://github.com/nithyasahasra/business-idea-validator/blob/main/search_service.py): `search_service.py`
- [Report synthesis](https://github.com/nithyasahasra/business-idea-validator/blob/main/llm_service.py): `llm_service.py`
- [Opportunity scoring](https://github.com/nithyasahasra/business-idea-validator/blob/main/scoring_service.py): `scoring_service.py`

### Persistence

- [Application database](https://github.com/nithyasahasra/business-idea-validator/blob/main/database.py): `database.py`

### Other components

- **Founder**
- **Tavily Search**
- **OpenAI**
- **Resend email**

## Connections

- Founder → React app: uses (evidence: `README`)
- React app → Sign-in and signup: routes to (evidence: `App.jsx`)
- React app → Email verification: routes to (evidence: `App.jsx`)
- React app → Idea submission: routes to (evidence: `App.jsx`)
- React app → Job progress: routes to (evidence: `App.jsx`)
- React app → Report history: routes to (evidence: `App.jsx`)
- React app → Validation report: routes to (evidence: `App.jsx`)
- Founder → Idea submission: submits idea (evidence: `README`)
- Sign-in and signup → Auth state: uses auth
- Idea submission → API client: submits via
- Job progress → API client: polls via
- Report history → API client: fetches via
- Validation report → API client: fetches via
- API client → FastAPI app: HTTP JSON (evidence: `README`)
- FastAPI app → Auth routes: registers (evidence: `main.py`)
- FastAPI app → Idea routes: registers (evidence: `main.py`)
- FastAPI app → Research routes: registers (evidence: `main.py`)
- FastAPI app → Report routes: registers (evidence: `main.py`)
- Auth routes → Auth service: delegates to
- Auth routes → Email delivery: sends email
- Email delivery → Resend email: sends via (evidence: `email_service.py`)
- Idea routes → Application database: queues job (evidence: `README`)
- Research worker → Application database: claims jobs (evidence: `worker.py`)
- Research worker → Research stages: processes job (evidence: `worker.py`)
- Research stages → Evidence search: collects evidence (evidence: `research_service.py`)
- Evidence search → Tavily Search: searches (evidence: `search_service.py`)
- Research stages → Application database: persists sources (evidence: `research_service.py`)
- Research stages → Report synthesis: synthesizes report (evidence: `research_service.py`)
- Report synthesis → OpenAI: generates report (evidence: `README`)
- Research stages → Opportunity scoring: calculates score (evidence: `research_service.py`)
- Research stages → Application database: persists report (evidence: `research_service.py`)
- Report routes → Application database: reads reports