System Components

**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]]

author	version	line-number	content
		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]]

Wiki source code of System Components