ideaforge/docs/architecture.md

architecture

Overview

IdeaForge is a dual-stack application: a Python FastAPI backend with SQLite storage and Claude API integration, fronted by a Flutter Web/Mobile client.

System Context

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

Backend Architecture

Layers

API Layer (FastAPI Routers)
    │
    ▼
Service Layer (Business Logic)
    │
    ├──▶ AI Module (Claude API Client)
    │
    ▼
Data Layer (SQLAlchemy Models + Pydantic Schemas)
    │
    ▼
Database (SQLite via aiosqlite)

Rules:

• Services never import from API layer
• API and CLI both depend on services
• AI module is a peer of services, injected as needed
• All database access goes through SQLAlchemy async sessions

Key Modules

Module	Responsibility
api/ideas.py	CRUD endpoints for ideas
api/evaluations.py	Evaluation endpoints (manual + AI)
services/idea_service.py	Idea business logic, filtering, ranking
services/evaluation_service.py	Evaluation orchestration
ai/client.py	Anthropic SDK wrapper
ai/evaluator.py	Prompt construction, response parsing
ai/prompts.py	Evaluation prompt templates

AI Evaluation Flow

Client triggers evaluation
    │
    ▼
POST /api/ideas/{id}/ai-evaluate
    │
    ▼
EvaluationService.run_ai_evaluation(idea_id)
    │
    ├──▶ Load idea + metrics from DB
    ├──▶ Build evaluation prompt (ai/prompts.py)
    ├──▶ Call Claude API (ai/client.py)
    ├──▶ Parse structured response (ai/evaluator.py)
    ├──▶ Store scores in DB
    │
    ▼
Return evaluation results with scores + reasoning

Demo Mode

When IDEAFORGE_DEMO_MODE=true:

• Database seeded with curated ideas on startup
• Write endpoints return 403 for unauthenticated requests
• AI evaluation rate-limited (N requests per hour per IP)
• Data resets on restart (ephemeral SQLite)

Frontend Architecture

Feature-First Structure

Each feature is self-contained with domain/data/presentation layers:

features/
├── ideas/
│   ├── domain/        # IdeaEntity, IdeaRepository (interface)
│   ├── data/          # IdeaDto, ApiIdeaRepository
│   └── presentation/  # IdeasController, IdeasScreen, IdeaCard
│
├── evaluation/
│   ├── domain/        # EvaluationEntity, MetricScore
│   ├── data/          # EvaluationDto, ApiEvaluationRepository
│   └── presentation/  # EvaluationController, ScoreRadarChart
│
└── dashboard/
    └── presentation/  # DashboardScreen, RankingTable

State Management

Riverpod providers manage all state:

• ideasControllerProvider — idea list with filters
• ideaDetailProvider(id) — single idea with evaluations
• evaluationControllerProvider — AI evaluation trigger and results

Key Screens

Screen	Path	Purpose
Ideas List	/ideas	Browse and filter ideas
Idea Detail	/ideas/:id	Full idea with scores and radar chart
Evaluate	/ideas/:id/evaluate	Trigger and view AI evaluation
Dashboard	/dashboard	Rankings and comparisons

Database Schema

Core tables (inherited from idea-manager):

• ideas — idea content (title, description, status, category)
• evaluation_metrics — metric definitions with scoring guides
• idea_evaluations — scores linking ideas to metrics
• tags / idea_tags — tagging system

Deployment

┌──────────────┐     ┌──────────────┐
│ Flutter Web   │     │ FastAPI      │
│ (Static CDN)  │────▶│ (Container)  │
└──────────────┘     └──────┬───────┘
                            │
                    ┌───────▼───────┐
                    │ SQLite Volume │
                    └───────────────┘

• Backend: Docker container on Fly.io / Railway
• Frontend: Static Flutter Web build on CDN
• Database: SQLite file on persistent volume