Kai Chappell
1fa9804be5
Set up IdeaForge project structure with documentation, architecture spec, and development guidelines for both backend (Python) and frontend (Flutter).
123 lines
3.8 KiB
Markdown
123 lines
3.8 KiB
Markdown
# 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.
|