Skip to Content

Wiki source code of System Components

Last modified by Robert Schaub on 2026/02/08 21:46
Hide last authors
Robert Schaub 1.1 1 = System Components =
2
3 === Component Interaction ===
4
5 {{mermaid}}
6 flowchart TB
7 subgraph Client["🖥️ Client Layer"]
8 BROWSER[Web Browser]
9 ANALYZE_PAGE["/analyze page (React)"]
10 JOBS_PAGE["/jobs page<br/>Job history & status"]
11 end
12
13 subgraph NextJS["⚡ Next.js Web App (apps/web)"]
14 direction TB
15
16 subgraph API_Routes["API Routes"]
17 ANALYZE_API["/api/fh/analyze<br/>━━━━━━━━━━━━━<br/>POST: Create job"]
18 JOBS_API["/api/fh/jobs<br/>━━━━━━━━━━━━━<br/>GET: List jobs<br/>POST: Create job"]
19 JOB_API["/api/fh/jobs/[id]<br/>━━━━━━━━━━━━━<br/>GET: Job status"]
20 EVENTS_API["/api/fh/jobs/[id]/events<br/>━━━━━━━━━━━━━<br/>GET: Job events (SSE)"]
21 RUN_JOB["/api/internal/run-job<br/>━━━━━━━━━━━━━<br/>POST: Execute analysis"]
22 end
23
24 subgraph Lib["Core Libraries"]
25 ANALYZER["analyzer.ts<br/>━━━━━━━━━━━━━<br/>AKEL Pipeline<br/>~6700 lines"]
26 RETRIEVAL["retrieval.ts<br/>━━━━━━━━━━━━━<br/>URL content extraction"]
27 WEBSEARCH["web-search.ts<br/>━━━━━━━━━━━━━<br/>Search abstraction"]
28 SR["source-reliability.ts<br/>━━━━━━━━━━━━━<br/>Source reliability (LLM+Cache)"]
29 end
30 end
31
32 subgraph DotNet["🔧 .NET API (apps/api)"]
33 DOTNET_API["FactHarbor.Api<br/>ASP.NET Core"]
34
35 subgraph Controllers["Controllers"]
36 ANALYZE_CTRL["AnalyzeController"]
37 JOBS_CTRL["JobsController"]
38 INTERNAL_CTRL["InternalJobsController"]
39 HEALTH_CTRL["HealthController"]
40 end
41
42 subgraph Services["Services"]
43 JOB_SVC["JobService"]
44 RUNNER_CLIENT["RunnerClient"]
45 end
46
47 DB[(SQLite Database<br/>factharbor.db)]
48 end
49
50 subgraph External["🌐 External Services"]
51 LLM["LLM Providers<br/>Anthropic / OpenAI / Google / Mistral"]
52 SEARCH["Search Providers<br/>Google CSE / SerpAPI"]
53 end
54
55 %% Client connections
56 BROWSER --> ANALYZE_PAGE
57 BROWSER --> JOBS_PAGE
58 ANALYZE_PAGE --> ANALYZE_API
59 JOBS_PAGE --> JOBS_API
60 JOBS_PAGE --> JOB_API
61 JOBS_PAGE --> EVENTS_API
62
63 %% Next.js internal
64 ANALYZE_API --> JOBS_CTRL
65 JOBS_API --> JOBS_CTRL
66 JOB_API --> JOBS_CTRL
67 EVENTS_API --> JOBS_CTRL
68 RUN_JOB --> ANALYZER
69
70 ANALYZER --> RETRIEVAL
71 ANALYZER --> WEBSEARCH
72 ANALYZER --> SR
73
74 %% .NET internal
75 ANALYZE_CTRL --> JOB_SVC
76 JOBS_CTRL --> JOB_SVC
77 INTERNAL_CTRL --> JOB_SVC
78 ANALYZE_CTRL --> RUNNER_CLIENT
79
80 JOB_SVC --> DB
81 RUNNER_CLIENT --> RUN_JOB
82
83 %% External connections
84 ANALYZER --> LLM
85 WEBSEARCH --> SEARCH
86 RETRIEVAL --> External
87 {{/mermaid}}
88
89 === Key Files ===
90
91 |= File |= Purpose |= Size
92 | ##apps/web/src/lib/analyzer.ts## | Core analysis engine (AKEL pipeline) | ~6700 lines
93 | ##apps/web/src/lib/retrieval.ts## | URL/PDF content extraction | ~500 lines
94 | ##apps/web/src/lib/web-search.ts## | Search provider abstraction | ~300 lines
95 | ##apps/web/src/lib/source-reliability.ts## | Source reliability scoring | ~200 lines
96 | ##apps/web/src/app/jobs/[id]/page.tsx## | Job results UI | ~800 lines
97 | ##apps/api/Controllers/JobsController.cs## | Job CRUD API | ~200 lines
98 | ##apps/api/Data/FhDbContext.cs## | Database context | ~100 lines
99 | ##apps/api/Services/RunnerClient.cs## | Runner invocation with retry logic | ~150 lines
100
101 ----
102
103 == Unified Config Management (UCM) ==
104
105 FactHarbor uses UCM for all runtime configuration. UCM provides:
106 * File-backed defaults with schema versioning
107 * Admin UI for runtime configuration changes
108 * Bidirectional sync between DB and files (development mode)
109 * Drift detection and config validation
110
111 === UCM Architecture ===
112
113 {{mermaid}}
114 flowchart TB
115 subgraph AdminUI [Admin UI]
116 Tabs[Config Type Tabs]
117 Editor[Editor/Form]
118 History[Version History]
119 Compare[Compare View]
120 end
121
122 subgraph ConfigTypes [Configuration Types]
123 Pipeline[Pipeline]
124 Search[Search]
125 Calc[Calculation]
126 SR[Source Reliability]
127 Prompts[Prompts]
128 Lexicons[Lexicons]
129 end
130
131 subgraph Storage [SQLite Storage]
132 ConfigBlobs[config_blobs<br/>immutable content]
133 ConfigActive[config_active<br/>activation pointers]
134 ConfigUsage[config_usage<br/>per-job tracking]
135 end
136
137 subgraph Validation [Validation Layer]
138 ZodSchemas[Zod Schemas]
139 Canonicalize[Canonicalization]
140 end
141
142 Tabs --> ConfigTypes
143 ConfigTypes --> ZodSchemas
144 ZodSchemas --> Canonicalize
145 Canonicalize --> ConfigBlobs
146 ConfigBlobs --> ConfigActive
147 ConfigActive --> ConfigUsage
148 {{/mermaid}}
149
150 === Configuration File Organization ===
151
152 FactHarbor uses a hybrid config storage model:
153
154 |= Config Type |= File Location |= Format |= UCM Domain
155 | Pipeline/Search/Calc | ##apps/web/configs/## | JSON | Yes
156 | Prompts | ##apps/web/prompts/## | Markdown | Yes
157 | Source Reliability | ##apps/web/configs/## | JSON | Yes (separate)
158 | Lexicons | ##apps/web/configs/## | JSON | Yes
159
160 **Rationale:** Prompts are version-controlled text that benefits from Markdown
161 formatting and line-based diffs. Structured configs benefit from JSON schema
162 validation and programmatic manipulation.
163
164 === Source of Truth Hierarchy ===
165 1. **Runtime Authority:** Database (what the app actually uses)
166 1. **Default Templates:** JSON files in ##apps/web/configs/##
167 1. **Fallback:** Code constants in ##config-schemas.ts##
168
169 See Unified_Config_Management.md (in User Guides) for details.
170
171 ----
172
173 **Navigation:** [[Architecture Overview>>FactHarbor.Specification.Implementation.Architecture Overview.WebHome]] | Prev: [[Data Models>>FactHarbor.Specification.Implementation.Architecture Overview.Data Models.WebHome]] | Next: [[Implementation Status and Quality>>FactHarbor.Specification.Implementation.Architecture Overview.Implementation Status and Quality.WebHome]]
174