Skip to Content

Wiki source code of Design Decisions

Last modified by Robert Schaub on 2025/12/18 12:03
Show last authors
1 = Design Decisions =
2 This page explains key architectural choices in FactHarbor and why simpler alternatives were chosen over complex solutions.
3 **Philosophy**: Start simple, add complexity only when metrics prove necessary.
4 == 1. Single Primary Database (PostgreSQL) ==
5 **Decision**: Use PostgreSQL for all data initially, not multiple specialized databases
6 **Alternatives considered**:
7 * ❌ PostgreSQL + TimescaleDB + Elasticsearch from day one
8 * ❌ Multiple specialized databases (graph, document, time-series)
9 * ❌ Microservices with separate databases
10 **Why PostgreSQL alone**:
11 * Modern PostgreSQL handles most workloads excellently
12 * Built-in full-text search often sufficient
13 * Time-series extensions available (pg_timeseries)
14 * Simpler deployment and maintenance
15 * Lower infrastructure costs
16 * Easier to reason about
17 **When to add specialized databases**:
18 * Elasticsearch: When PostgreSQL search consistently >500ms
19 * TimescaleDB: When metrics queries consistently >1s
20 * Graph DB: If relationship queries become complex
21 **Evidence**: Research shows single-DB architectures work well until 10,000+ users (Vertabelo, AWS patterns)
22 == 2. Three-Layer Architecture ==
23 **Decision**: Organize system into 3 layers (Interface, Processing, Data)
24 **Alternatives considered**:
25 * ❌ 7 layers (Ingestion, AKEL, Quality, Publication, Improvement, UI, Moderation)
26 * ❌ Pure microservices (20+ services)
27 * ❌ Monolithic single-layer
28 **Why 3 layers**:
29 * Clear separation of concerns
30 * Easy to understand and explain
31 * Maintainable by small team
32 * Can scale each layer independently
33 * Reduces cognitive load
34 **Research**: Modern architecture best practices recommend 3-4 layers maximum for maintainability
35 == 3. Deferred Federation ==
36 **Decision**: Single-node architecture for V1.0, federation only in V2.0+
37 **Alternatives considered**:
38 * ❌ Federated from day one
39 * ❌ P2P architecture
40 * ❌ Blockchain-based
41 **Why defer federation**:
42 * Adds massive complexity (sync, conflicts, identity, governance)
43 * Not needed for first 10,000 users
44 * Core product must be proven first
45 * Most successful platforms start centralized (Wikipedia, Reddit, GitHub)
46 * Can add federation later (see: Mastodon, Matrix)
47 **When to implement**:
48 * 10,000+ users on single node
49 * Users explicitly request decentralization
50 * Geographic distribution becomes necessary
51 * Censorship becomes real problem
52 **Evidence**: Research shows premature federation increases failure risk (InfoQ MVP architecture)
53 == 4. Parallel AKEL Processing ==
54 **Decision**: Process evidence/sources/scenarios in parallel, not sequentially
55 **Alternatives considered**:
56 * ❌ Pure sequential pipeline (15-30 seconds)
57 * ❌ Fully async/event-driven (complex orchestration)
58 * ❌ Microservices per stage
59 **Why parallel**:
60 * 40% faster (10-18s vs 15-30s)
61 * Better resource utilization
62 * Same code complexity
63 * Improves user experience
64 **Implementation**: Simple parallelization within single AKEL worker
65 **Evidence**: LLM orchestration research (2024-2025) strongly recommends pipeline parallelization
66 == 5. Simple Manual Roles ==
67 **Decision**: Manual role assignment for V1.0 (Reader, Contributor, Moderator, Admin)
68 **Alternatives considered**:
69 * ❌ Complex reputation point system from day one
70 * ❌ Automated privilege escalation
71 * ❌ Reputation decay algorithms
72 * ❌ Trust graphs
73 **Why simple roles**:
74 * Complex reputation not needed until 100+ active contributors
75 * Manual review builds better community initially
76 * Easier to implement and maintain
77 * Can add automation later when needed
78 **When to add complexity**:
79 * 100+ active contributors
80 * Manual role management becomes bottleneck
81 * Clear abuse patterns emerge requiring automation
82 **Evidence**: Successful communities (Wikipedia, Stack Overflow) started simple and added complexity gradually
83 == 6. One-to-Many Scenarios ==
84 **Decision**: Scenarios belong to single claims (one-to-many) for V1.0
85 **Alternatives considered**:
86 * ❌ Many-to-many with junction table
87 * ❌ Scenarios as separate first-class entities
88 * ❌ Hierarchical scenario taxonomy
89 **Why one-to-many**:
90 * Simpler queries (no junction table)
91 * Easier to understand
92 * Sufficient for most use cases
93 * Can add many-to-many in V2.0 if requested
94 **When to add many-to-many**:
95 * Users request "apply this scenario to other claims"
96 * Clear use cases for scenario reuse emerge
97 * Performance doesn't degrade
98 **Trade-off**: Slight duplication of scenarios vs. simpler mental model
99 == 7. Two-Tier Edit History ==
100 **Decision**: Hot audit trail (PostgreSQL) + Cold debug logs (S3 archive)
101 **Alternatives considered**:
102 * ❌ Everything in PostgreSQL forever
103 * ❌ Everything archived immediately
104 * ❌ Complex versioning system from day one
105 **Why two-tier**:
106 * 90% reduction in hot database size
107 * Full traceability maintained
108 * Faster queries (hot data only)
109 * Lower storage costs (S3 cheaper)
110 **Implementation**:
111 * Hot: Human edits, moderation actions, major AKEL updates
112 * Cold: All AKEL processing logs (archived after 90 days)
113 **Evidence**: Standard pattern for high-volume audit systems
114 == 8. Denormalized Cache Fields ==
115 **Decision**: Store summary data in claim records (evidence_summary, source_names, scenario_count)
116 **Alternatives considered**:
117 * ❌ Fully normalized (join every time)
118 * ❌ Fully denormalized (duplicate everything)
119 * ❌ External cache only (Redis)
120 **Why selective denormalization**:
121 * 70% fewer joins on common queries
122 * Much faster claim list/search pages
123 * Trade-off: Small storage increase (~10%)
124 * Read-heavy system (95% reads) benefits greatly
125 **Update strategy**:
126 * Immediate: On user-visible edits
127 * Deferred: Background job every hour
128 * Invalidation: On source data changes
129 **Evidence**: Content management best practices recommend denormalization for read-heavy systems
130 == 9. Multi-Provider LLM Orchestration ==
131 **Decision**: Abstract LLM calls behind interface, support multiple providers
132 **Alternatives considered**:
133 * ❌ Hard-coded to single LLM provider
134 * ❌ Switch providers manually
135 * ❌ Complex multi-agent system
136 **Why orchestration**:
137 * No vendor lock-in
138 * Cost optimization (use cheap models for simple tasks)
139 * Cross-checking (compare outputs)
140 * Resilience (automatic fallback)
141 **Implementation**: Simple routing layer, task-based provider selection
142 **Evidence**: Modern LLM app architecture (2024-2025) strongly recommends orchestration
143 == 10. Source Scoring Separation ==
144 **Decision**: Separate source scoring (weekly batch) from claim analysis (real-time)
145 **Alternatives considered**:
146 * ❌ Update source scores during claim analysis
147 * ❌ Real-time score calculation
148 * ❌ Complex feedback loops
149 **Why separate**:
150 * Prevents circular dependencies
151 * Predictable behavior
152 * Easier to reason about
153 * Simpler testing
154 * Clear audit trail
155 **Implementation**:
156 * Sunday 2 AM: Calculate scores from past week
157 * Monday-Saturday: Claims use those scores
158 * Never update scores during analysis
159 **Evidence**: Standard pattern to prevent feedback loops in ML systems
160 == 11. Simple Versioning ==
161 **Decision**: Basic audit trail only for V1.0 (before/after values, who/when/why)
162 **Alternatives considered**:
163 * ❌ Full Git-like versioning from day one
164 * ❌ Branching and merging
165 * ❌ Time-travel queries
166 * ❌ Automatic conflict resolution
167 **Why simple**:
168 * Sufficient for accountability and basic rollback
169 * Complex versioning not requested by users yet
170 * Can add later if needed
171 * Easier to implement and maintain
172 **When to add complexity**:
173 * Users request "see version history"
174 * Users request "restore previous version"
175 * Need for branching emerges
176 **Evidence**: "You Aren't Gonna Need It" (YAGNI) principle from Extreme Programming
177 == Design Philosophy ==
178 **Guiding Principles**:
179 1. **Start Simple**: Build minimum viable features
180 2. **Measure First**: Add complexity only when metrics prove necessity
181 3. **User-Driven**: Let user requests guide feature additions
182 4. **Iterate**: Evolve based on real-world usage
183 5. **Fail Fast**: Simple systems fail in simple ways
184 **Inspiration**:
185 * "Premature optimization is the root of all evil" - Donald Knuth
186 * "You Aren't Gonna Need It" - Extreme Programming
187 * "Make it work, make it right, make it fast" - Kent Beck
188 **Result**: FactHarbor V1.0 is 35% simpler than original design while maintaining all core functionality and actually becoming more scalable.
189 == Related Pages ==
190 * [[Architecture>>FactHarbor.Specification.Architecture.WebHome]]
191 * [[When to Add Complexity>>FactHarbor.Specification.When-to-Add-Complexity]]
192 * [[Data Model>>FactHarbor.Specification.Data Model.WebHome]]
193 * [[AKEL>>FactHarbor.Specification.AI Knowledge Extraction Layer (AKEL).WebHome]]