chore: initial project scaffold

Set up IdeaForge project structure with documentation, architecture spec,
and development guidelines for both backend (Python) and frontend (Flutter).

readme.md

@@ -0,0 +1,122 @@
+# 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.