# ideaforge

A full-stack idea management platform with AI-powered evaluation. Browse, filter, and
evaluate software project ideas using quantitative metrics and automated AI scoring.

## Architecture

IdeaForge is a dual-stack project:

- **Backend:** Python API (FastAPI) with SQLite storage and Claude API integration
- **Frontend:** Flutter Web/Mobile client with radar charts and real-time evaluation

```
┌─────────────────┐     ┌─────────────────┐     ┌──────────────┐
│  Flutter Client  │────▶│   FastAPI        │────▶│  Claude API  │
│  (Web / Mobile)  │◀────│   Backend        │◀────│  (Evaluation)│
└─────────────────┘     └────────┬────────┘     └──────────────┘
                                 │
                        ┌────────▼────────┐
                        │     SQLite      │
                        │   (ideas.db)    │
                        └─────────────────┘
```

## Features

- **Idea browsing** — Filter by status, category, and tags
- **Metric scoring** — 8 quantitative evaluation metrics (feasibility, market potential,
  uniqueness, personal interest, learning value, time to MVP, monetisation, maintenance)
- **AI evaluation** — Trigger Claude API to score ideas against all metrics with reasoning
- **Score visualisation** — Radar/spider charts showing metric profiles
- **Comparison** — Side-by-side idea comparison with aggregate rankings
- **Demo mode** — Public instance with curated ideas (read-only, rate-limited AI)

## Stack

### Backend

| Component | Technology |
|-----------|-----------|
| API Framework | FastAPI 0.115+ |
| ORM | SQLAlchemy 2.0+ (async) |
| Database | SQLite + aiosqlite |
| Validation | Pydantic 2.10+ |
| AI | Anthropic Python SDK |
| Logging | structlog |
| Migrations | Alembic |
| Package Manager | uv |

### Frontend

| Component | Technology |
|-----------|-----------|
| Framework | Flutter 3.27+ |
| State | Riverpod 3.1+ |
| Navigation | GoRouter |
| HTTP | dio |
| Charts | fl_chart |

## Getting Started

### Backend

```bash
cd backend/
uv sync
uv run alembic upgrade head
uv run ideaforge db init
uv run ideaforge serve
```

API available at [http://localhost:8000](http://localhost:8000).
Docs at [http://localhost:8000/docs](http://localhost:8000/docs).

### Frontend

```bash
cd frontend/
flutter pub get
dart run build_runner build --delete-conflicting-outputs
flutter run -d chrome
```

## Configuration

Backend configuration via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `IDEAFORGE_DATABASE_URL` | `sqlite+aiosqlite:///data/ideas.db` | Database path |
| `IDEAFORGE_HOST` | `127.0.0.1` | API host |
| `IDEAFORGE_PORT` | `8000` | API port |
| `IDEAFORGE_ANTHROPIC_API_KEY` | — | Claude API key (required for AI eval) |
| `IDEAFORGE_DEMO_MODE` | `false` | Enable demo mode (read-only, rate-limited) |
| `IDEAFORGE_LOG_LEVEL` | `INFO` | Log level |
| `IDEAFORGE_LOG_FORMAT` | `json` | Log format (`json` or `console`) |

## Testing

```bash
# Backend
cd backend/
uv run pytest --cov=src/ideaforge

# Frontend
cd frontend/
flutter test --coverage
```

## Relationship to idea-manager

IdeaForge extends the [idea-manager](https://gitea.kschappell.com/kschappell/idea-manager)
project. The backend shares the same data model and evaluation framework, adding:

- Claude API integration for automated evaluation
- Demo mode for public deployment
- Optimised API endpoints for the Flutter client
- Docker deployment configuration

## License

All rights reserved. Kai Chappell.