FounderOS

FounderOS is an AI-powered startup idea validation platform. A founder enters a business idea, locality, and launch budget, then receives an investor-style report generated by autonomous analysis agents. The app streams live agent progress to the UI and saves completed reports in MongoDB.

What It Does

• Validates startup and local business ideas with multi-agent analysis.
• Generates market, competitor, timing, risk, scoring, feasibility, and budget insights.
• Finds local physical-business competitors using Google Places, Foursquare, OpenStreetMap, Overpass, and DuckDuckGo fallbacks.
• Streams live analysis progress with Socket.IO.
• Persists analyses, reports, approvals, and generated jobs in MongoDB.

Tech Stack

• Frontend: React 18, Vite, Tailwind CSS, Framer Motion, Recharts
• API: Node.js, Express, Socket.IO, Mongoose
• AI service: Python, Flask
• Database: MongoDB
• AI providers: Groq first, Gemini fallback, deterministic local fallback when no key is configured

Project Structure

FounderOS/
  client/       React + Vite web app
  server/       Express API, auth, analyses, jobs, Socket.IO
  ai-service/   Flask service that runs each AI analysis agent

Prerequisites

• Node.js 18+
• Python 3.10+
• MongoDB running locally
• Optional: Groq, Gemini, Google Maps, and Foursquare API keys for richer live output

Default local ports:

Client:      http://localhost:5173
Express API: http://localhost:5000
AI service:  http://localhost:8000
MongoDB:     mongodb://localhost:27017/founderos

Environment Setup

From the repo root:

Copy-Item .env.example server\.env
Copy-Item .env.example ai-service\.env

Update server\.env as needed:

MONGODB_URI=mongodb://localhost:27017/founderos
CLIENT_URL=http://localhost:5173
CLIENT_URLS=http://localhost:5173,http://127.0.0.1:5173
SERVER_PORT=5000
AI_SERVICE_URL=http://localhost:8000

Update ai-service\.env as needed:

GROQ_API_KEY=your_groq_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
FLASK_PORT=8000
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
FOURSQUARE_API_KEY=your_foursquare_places_api_key_here

API keys are optional for local testing. If no LLM key is available, the Flask service returns structured fallback output so the full product flow can still be tested.

Install Dependencies

Install all Node dependencies:

npm run install:all

Create the Python virtual environment and install Flask service dependencies:

cd ai-service
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
cd ..

Run Locally

1. Start MongoDB locally.

2. Start the AI service in one terminal:

cd ai-service
.\.venv\Scripts\activate
python app.py

3. Start the Express API and React client from the repo root in another terminal:

npm run dev

4. Open the app:

http://localhost:5173

Health Checks

Check the Express API:

Invoke-RestMethod http://localhost:5000/health

Expected response:

{ "ok": true, "service": "founderos-api" }

Check the Flask AI service:

Invoke-RestMethod http://localhost:8000/health

Expected response includes:

{ "ok": true, "service": "founderos-ai" }

API Smoke Test

This creates a demo founder account, submits a cafe idea for Maruti Mandir, Ratnagiri, and polls until the report completes.

$email = "demo.$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())@example.com"

$signupBody = @{
  name = "Demo Founder"
  email = $email
  password = "demo1234"
  role = "founder"
  region = "Maruti Mandir, Ratnagiri"
} | ConvertTo-Json

$signup = Invoke-RestMethod `
  -Uri http://localhost:5000/api/auth/signup `
  -Method Post `
  -ContentType "application/json" `
  -Body $signupBody

$analysisBody = @{
  idea = "A cozy premium cafe serving specialty coffee, snacks, and quick bites for students and local professionals"
  region = "Maruti Mandir, Ratnagiri"
  budget = 500000
  ownsPlace = $false
} | ConvertTo-Json

$created = Invoke-RestMethod `
  -Uri http://localhost:5000/api/analyses `
  -Method Post `
  -Headers @{ Authorization = "Bearer $($signup.token)" } `
  -ContentType "application/json" `
  -Body $analysisBody

$id = $created.analysis._id

for ($i = 1; $i -le 40; $i++) {
  Start-Sleep -Seconds 5
  $current = Invoke-RestMethod `
    -Uri "http://localhost:5000/api/analyses/$id" `
    -Method Get `
    -Headers @{ Authorization = "Bearer $($signup.token)" }

  Write-Output "status=$($current.analysis.status); currentAgent=$($current.analysis.currentAgent)"

  if ($current.analysis.status -eq "completed" -or $current.analysis.status -eq "failed") {
    $current.analysis.report | ConvertTo-Json -Depth 8
    break
  }
}

Successful runs should move through the analysis agents and end with status=completed.

Verified Demo Run

The API was tested with:

Idea: A cozy premium cafe serving specialty coffee, snacks, and quick bites for students and local professionals
Area: Maruti Mandir, Ratnagiri
Budget: INR 500,000

Result:

• Express API health check passed.
• Flask AI health check passed.
• Analysis completed successfully.
• Live local competitor discovery returned cafe competitors around Ratnagiri, including Pokket Cafe Ratnagiri, Kafe Ratnagiri Local, Cafe Good Vibes, Cafe AM PM, and Cafe Hash Tag Ratnagiri.

Useful Scripts

npm run install:all   # install root, client, and server Node dependencies
npm run dev           # run Express API and Vite client together
npm run dev:client    # run only the Vite client
npm run dev:server    # run only the Express API
npm run build         # build the React app
npm run start         # start the Express API in production mode

Troubleshooting

• If the client cannot reach the API, confirm CLIENT_URLS includes the browser origin you are using.
• If the API returns Sign in required, create or sign in to a founder account before calling /api/analyses.
• If analyses remain stuck, check that http://localhost:8000/health is reachable from the machine running the Express server.
• If MongoDB is not running, the API may start but auth and analysis persistence will fail.
• If local competitor results look sparse, add GOOGLE_MAPS_API_KEY or FOURSQUARE_API_KEY to ai-service\.env.