Wiki source code of Tools Decisions
Version 2.1 by Robert Schaub on 2025/12/25 21:20
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | = Tools Decisions = |
| 2 | |||
| 3 | == Purpose == | ||
| 4 | |||
| |
2.1 | 5 | This page documents the deliberate tool choices for FactHarbor from **POC1 to Beta**. The guiding principles are: |
| 6 | |||
| 7 | * minimal setup and cognitive load for POC1 | ||
| 8 | * no rewrites when moving to Beta | ||
| 9 | * clear, incremental upgrade paths | ||
| 10 | |||
| |
1.1 | 11 | ---- |
| 12 | |||
| 13 | == Phase 1 — POC1 (Local, Low Infrastructure) == | ||
| 14 | |||
| |
2.1 | 15 | === Principles === |
| |
1.1 | 16 | |
| |
2.1 | 17 | * Local-first development |
| 18 | * No mandatory container or cloud infrastructure | ||
| 19 | * Same architectural shape as later phases | ||
| |
1.1 | 20 | |
| |
2.1 | 21 | === Backend === |
| |
1.1 | 22 | |
| |
2.1 | 23 | * ((( |
| 24 | **ASP.NET Core (.NET 8)** | ||
| |
1.1 | 25 | |
| |
2.1 | 26 | * Role: system of record (jobs, status, results, events) |
| 27 | * Reason: strong typing, long-term stability, C# expertise | ||
| 28 | ))) | ||
| 29 | * ((( | ||
| 30 | **SQLite (EF Core provider)** | ||
| |
1.1 | 31 | |
| |
2.1 | 32 | * Role: local persistence |
| 33 | * Reason: zero setup, file-based, smooth transition to PostgreSQL | ||
| 34 | ))) | ||
| |
1.1 | 35 | |
| |
2.1 | 36 | === Frontend & Orchestration === |
| |
1.1 | 37 | |
| |
2.1 | 38 | * ((( |
| 39 | **Next.js (TypeScript)** | ||
| |
1.1 | 40 | |
| |
2.1 | 41 | * Role: UI and AI orchestration |
| 42 | * Reason: fast iteration, strong ecosystem, good AI tooling | ||
| 43 | ))) | ||
| 44 | * ((( | ||
| 45 | **Vercel AI SDK** | ||
| 46 | |||
| 47 | * Role: LLM abstraction | ||
| 48 | * Reason: OpenAI-first, Claude-ready, provider switching without rewrites | ||
| 49 | ))) | ||
| 50 | |||
| 51 | === AI Providers === | ||
| 52 | |||
| 53 | * OpenAI (default) | ||
| 54 | * Anthropic (optional, later) | ||
| 55 | |||
| 56 | === Editors === | ||
| 57 | |||
| 58 | * Visual Studio 2022 — primary for .NET API | ||
| 59 | * Cursor or VS Code — primary for Next.js / TypeScript | ||
| 60 | |||
| |
1.1 | 61 | ---- |
| 62 | |||
| |
2.1 | 63 | == Phase 2 — Transition to Beta == |
| |
1.1 | 64 | |
| 65 | === Changes (No Rewrite) === | ||
| |
2.1 | 66 | |
| 67 | * SQLite → PostgreSQL | ||
| 68 | * Local execution → hosted environments | ||
| |
1.1 | 69 | * Add authentication, quotas, persistence hardening |
| 70 | |||
| 71 | === Additional Tools Introduced === | ||
| |
2.1 | 72 | |
| 73 | * Docker (optional, mainly for DB parity) | ||
| 74 | * Managed PostgreSQL | ||
| 75 | * GitHub Actions (CI) | ||
| 76 | * Hosting: | ||
| |
1.1 | 77 | ** Next.js → Vercel |
| |
2.1 | 78 | ** .NET API → Azure App Service or Container Apps |
| |
1.1 | 79 | |
| 80 | ---- | ||
| 81 | |||
| |
2.1 | 82 | == Explicitly Deferred == |
| 83 | |||
| |
1.1 | 84 | * Kubernetes |
| |
2.1 | 85 | * Microservice decomposition |
| 86 | * Complex distributed queues | ||
| |
1.1 | 87 | * Multi-region deployment |
| 88 | |||
| 89 | These are intentionally deferred to reduce early risk. | ||
| 90 | |||
| 91 | ---- | ||
| 92 | |||
| |
2.1 | 93 | == Summary == |
| 94 | |||
| |
1.1 | 95 | * Architecture is stable from POC1 onward |
| 96 | * Infrastructure is phased, not front-loaded | ||
| |
2.1 | 97 | * Tool choices prioritize clarity and durability over novelty |