IdeaGo

Decision-first source intelligence for startup ideas.

IdeaGo turns a rough product idea into a structured validation report with recommendation, why-now framing, pain signals, commercial signals, whitespace opportunities, competitors, evidence, and confidence.

简体中文 · Quick Start · Branch Scope · How It Works · Deployment · Trellis Spec

---

Overview

This README describes the main branch.

main is the anonymous and personal-deployment line of IdeaGo. It keeps the same Source Intelligence V2 analysis engine as saas, but intentionally excludes hosted runtime concerns:

• no login
• no profile system
• no Supabase requirement to boot
• no admin dashboard
• no billing or pricing UI

If you need the hosted product with auth, profile ownership, admin APIs, and SaaS deployment behavior, switch to the saas branch.

What Lives On main

Current product contract

IdeaGo is not just a competitor lookup flow anymore. The report contract is decision-first:

1. recommendation and why-now
2. pain signals
3. commercial signals
4. whitespace opportunities
5. competitors
6. evidence
7. confidence

Current runtime surface

• anonymous idea submission
• transient /reports/new handoff before the persisted report id is known
• SSE progress streaming with capped reconnects and /status fallback
• local file-cache persistence for report history
• report detail and markdown export
• stable anonymous X-Session-Id headers generated by the frontend client
• local SQLite checkpoints for LangGraph state
• no account ownership model

Current route surface

• /
• /reports
• /reports/:id

The codebase contains some additional shared/legal UI files, but the active router on main stays intentionally small and anonymous.

Idea submission first transitions through /reports/new as an anonymous creation state before the real report id is available. That state is intentionally handled inside the report route flow instead of being exposed as a permanent standalone page.

Operational safeguards now baked into main:

• production logging keeps backtrace and diagnose off by default
• API responses include a baseline Content-Security-Policy
• /reports* rate limiting is bucketed separately for read, status, stream, and mutation flows
• the report UI keeps decision-first sections aligned as recommendation, why-now, pain, commercial, whitespace, competitors, evidence, confidence

Product Walkthrough

Landing And Idea Intake

Real-Time Research Pipeline

Decision Summary

Evidence-Backed Landscape

Quick Start

Prerequisites

• Python 3.10+
• uv
• Node.js 20+
• pnpm

Minimum useful secret:

• OPENAI_API_KEY

Recommended for better data coverage:

• TAVILY_API_KEY
• GITHUB_TOKEN
• PRODUCTHUNT_DEV_TOKEN
• REDDIT_CLIENT_ID
• REDDIT_CLIENT_SECRET

Install

uv sync --all-extras
pnpm --prefix frontend install

Frontend package management on main is pnpm only. Do not use the npm CLI and do not commit npm lockfiles.

Configure

cp .env.example .env
cp frontend/.env.example frontend/.env

Minimum practical configuration:

• OPENAI_API_KEY

Common local runtime settings:

• CACHE_DIR
• ANONYMOUS_CACHE_TTL_HOURS
• FILE_CACHE_MAX_ENTRIES
• LANGGRAPH_CHECKPOINT_DB_PATH
• RATE_LIMIT_ANALYZE_MAX
• RATE_LIMIT_ANALYZE_WINDOW_SECONDS
• RATE_LIMIT_REPORTS_MAX
• RATE_LIMIT_REPORTS_WINDOW_SECONDS
• CORS_ALLOW_ORIGINS

Frontend config on main is intentionally small:

• VITE_API_BASE_URL
• VITE_SENTRY_DSN if desired

No frontend env var is required for anonymous session identity or SSE recovery. The browser client automatically:

• generates a stable X-Session-Id
• sends it on report reads, export, and streaming requests
• falls back from SSE reconnect exhaustion to /api/v1/reports/{id}/status

Run In Development

Terminal 1:

uv run uvicorn ideago.api.app:create_app --factory --reload --port 8000

Terminal 2:

pnpm --prefix frontend dev

Open:

• frontend: http://localhost:5173
• backend health: http://localhost:8000/api/v1/health

Single-Process Local Run

pnpm --prefix frontend build
uv run python -m ideago

Open: http://localhost:8000

Docker Compose

main ships with a simple docker-compose.yml that pulls the published image from Docker Hub:

docker compose pull
docker compose up -d

Optional: pin to a release tag instead of latest:

IDEAGO_IMAGE_TAG=0.3.9 docker compose up -d

If you prefer to build from source, the branch also includes a Dockerfile.

How It Works

IdeaGo runs an explicit Source Intelligence V2 pipeline:

intent_parser -> query_planning_rewriting -> platform_adaptation -> sources -> extractor -> aggregator

That pipeline produces a decision-first report which is then persisted locally for later reopening.

flowchart TD
    A["User idea"] --> B["POST /api/v1/analyze"]
    B --> C["LangGraph engine"]
    C --> D["Intent parsing"]
    D --> E["Query planning + rewriting"]
    E --> F["Platform adaptation"]
    F --> G{"Local cache hit?"}
    G -->|Yes| H["Return persisted report"]
    G -->|No| I["Fetch six live sources"]
    I --> J["Extract structured signals"]
    J --> K["Aggregate findings"]
    K --> L["Assemble decision-first report"]
    L --> M["Persist report + runtime status"]
    M --> N["History / detail / export"]
    C -.-> O["SSE progress stream"]

Loading

Fixed source roles:

• Tavily for broad recall
• Reddit for pain and migration language
• GitHub for open-source maturity and ecosystem signals
• Hacker News for builder sentiment
• App Store for review-cluster pain
• Product Hunt for launch positioning

API Overview

Public API on main:

• POST /api/v1/analyze
• GET /api/v1/reports
• GET /api/v1/reports/{id}
• GET /api/v1/reports/{id}/status
• GET /api/v1/reports/{id}/stream
• GET /api/v1/reports/{id}/export
• DELETE /api/v1/reports/{id}
• DELETE /api/v1/reports/{id}/cancel
• GET /api/v1/health

main does not expose auth, billing, profile, pricing, or admin APIs.

Anonymous request behavior:

• mutating requests still require X-Requested-With
• report reads, status, stream, and export attach a stable client-generated X-Session-Id
• report throttling is isolated across read, status, stream, and mutation buckets

Configuration Notes

Important settings on main:

• OPENAI_API_KEY
• OPENAI_MODEL
• TAVILY_API_KEY
• CACHE_DIR
• ANONYMOUS_CACHE_TTL_HOURS
• FILE_CACHE_MAX_ENTRIES
• LANGGRAPH_CHECKPOINT_DB_PATH
• RATE_LIMIT_ANALYZE_MAX
• RATE_LIMIT_ANALYZE_WINDOW_SECONDS
• RATE_LIMIT_REPORTS_MAX
• RATE_LIMIT_REPORTS_WINDOW_SECONDS
• CORS_ALLOW_ORIGINS

Optional Reddit settings:

• REDDIT_CLIENT_ID
• REDDIT_CLIENT_SECRET
• REDDIT_ENABLE_PUBLIC_FALLBACK
• REDDIT_PUBLIC_FALLBACK_LIMIT
• REDDIT_PUBLIC_FALLBACK_DELAY_SECONDS

On main, public Reddit fallback is allowed by default unless you configure OAuth credentials.

Validation and report UX notes:

• query validation collapses whitespace before validation and requires at least 4 meaningful alphanumeric characters plus at least one letter
• the report page renders decision-first sections in this order: recommendation -> why-now -> pain -> commercial -> whitespace -> competitors -> evidence -> confidence
• SectionNav anchors follow the same order one-to-one

Project Structure

Backend

• src/ideago/api: FastAPI app, routes, middleware, schemas
• src/ideago/cache: local report persistence
• src/ideago/config: runtime settings
• src/ideago/models: domain models and report contracts
• src/ideago/pipeline: orchestration, extraction, aggregation, report assembly
• src/ideago/sources: six data-source adapters

Frontend

• frontend/src/app: router, shell, navbar, error boundary
• frontend/src/features/home: main search experience
• frontend/src/features/history: local report history
• frontend/src/features/reports: report detail and progress views
• frontend/src/lib/api: typed API client and SSE hook
• frontend/src/lib/i18n: locale setup and translations
• frontend/src/components/ui: shared UI primitives

Branch Model

• main: anonymous/personal deployment line
• saas: hosted/commercial line

Sync rule:

• shared product work lands on main
• saas pulls from main
• do not move hosted-only runtime dependencies back into main

Documentation Map

• Trellis spec entrypoint: .trellis/spec/README.md
• Backend conventions: .trellis/spec/backend/index.md
• Frontend conventions: .trellis/spec/frontend/index.md
• Settings and env vars: .trellis/spec/backend/config-logging.md
• Deployment runbook: DEPLOYMENT.md

Verification

Run what applies before you call a change complete:

# Backend
uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run mypy src
uv run pytest

# Frontend
pnpm --prefix frontend lint
pnpm --prefix frontend typecheck
pnpm --prefix frontend test
pnpm --prefix frontend build