Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817
This commit is contained in:
Public Source Publisher committed
commit
ad8ad252a9
825 files changed
+124216
No files matched your search
@@ -0,0 +1,203 @@
|
||||
# System architecture
|
||||
|
||||
## Decision summary
|
||||
|
||||
The first release is a **modular monolith** deployed as one application container plus
|
||||
PostgreSQL.
|
||||
|
||||
The production application contains:
|
||||
|
||||
- ASP.NET Core API and authentication;
|
||||
- compiled React static assets;
|
||||
- application/use-case modules;
|
||||
- background hosted services;
|
||||
- filesystem attachment adapter;
|
||||
- import/export and backup orchestration.
|
||||
|
||||
This topology minimizes operational overhead on Unraid while retaining internal
|
||||
boundaries that can be tested and evolved.
|
||||
|
||||
## Context
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
User[Browser user] -->|HTTPS| Proxy[Reverse proxy]
|
||||
Proxy --> App[ItWorx Knowledge Hub]
|
||||
ApiClient[Scoped API client] -->|HTTPS /api/v1| Proxy
|
||||
App --> Db[(PostgreSQL)]
|
||||
App --> Files[(Attachments / imports / backups)]
|
||||
Leaf[Read-only LeafWiki snapshot] -->|Read-only import mount| App
|
||||
FutureMCP[Future separate MCP server] -.->|HTTPS /api/v1| Proxy
|
||||
```
|
||||
|
||||
The future MCP server is shown only as an external client. It is not built or deployed by
|
||||
this repository.
|
||||
|
||||
## Production containers
|
||||
|
||||
```text
|
||||
knowledge-hub
|
||||
postgres
|
||||
```
|
||||
|
||||
Development may run the React Vite server separately for fast refresh. Production serves
|
||||
its built files through ASP.NET Core.
|
||||
|
||||
## Logical projects
|
||||
|
||||
```text
|
||||
ItWorx.KnowledgeHub.Domain
|
||||
Pure domain concepts and invariants
|
||||
|
||||
ItWorx.KnowledgeHub.Application
|
||||
Use cases, authorization requirements, ports and orchestration
|
||||
|
||||
ItWorx.KnowledgeHub.Contracts
|
||||
Stable request/response and event contracts
|
||||
|
||||
ItWorx.KnowledgeHub.Infrastructure
|
||||
EF Core, PostgreSQL, files, hashing, import adapters, jobs
|
||||
|
||||
ItWorx.KnowledgeHub.Api
|
||||
HTTP, auth/session transport, middleware, static SPA hosting
|
||||
|
||||
src/frontend
|
||||
React application
|
||||
|
||||
tests/backend/*
|
||||
tests/e2e
|
||||
```
|
||||
|
||||
Allowed dependency direction:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Api --> Application
|
||||
Api --> Contracts
|
||||
Api --> Infrastructure
|
||||
Infrastructure --> Application
|
||||
Infrastructure --> Domain
|
||||
Infrastructure --> Contracts
|
||||
Application --> Domain
|
||||
Application --> Contracts
|
||||
```
|
||||
|
||||
Forbidden:
|
||||
|
||||
- Domain → Application/Infrastructure/API/UI
|
||||
- Application → Infrastructure/API/UI
|
||||
- Contracts → Infrastructure/API/UI
|
||||
- Frontend → database/filesystem
|
||||
|
||||
Architecture tests must enforce this.
|
||||
|
||||
## Application modules
|
||||
|
||||
Initial module boundaries:
|
||||
|
||||
- Identity
|
||||
- Workspaces
|
||||
- Knowledge
|
||||
- Search
|
||||
- Attachments
|
||||
- Projects
|
||||
- Decisions
|
||||
- Runbooks
|
||||
- Imports
|
||||
- Exports
|
||||
- Audit
|
||||
- Integration
|
||||
- Operations
|
||||
|
||||
Modules may share infrastructure composition but must not mutate each other's tables
|
||||
through ad hoc DbContext access. Cross-module operations use application contracts and a
|
||||
single transaction boundary where required.
|
||||
|
||||
## Data flow: publish page
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant UI
|
||||
participant API
|
||||
participant App as Application
|
||||
participant DB as PostgreSQL
|
||||
participant Outbox
|
||||
|
||||
UI->>API: PUT page + If-Match
|
||||
API->>App: PublishPage command
|
||||
App->>DB: Load page + authorization
|
||||
App->>App: Validate version, Markdown and links
|
||||
App->>DB: Update current page
|
||||
App->>DB: Insert immutable revision
|
||||
App->>DB: Replace derived link/search records
|
||||
App->>DB: Insert audit event
|
||||
App->>Outbox: Insert page.updated event
|
||||
DB-->>App: Commit
|
||||
App-->>API: DTO + new ETag
|
||||
API-->>UI: 200 OK
|
||||
```
|
||||
|
||||
## Data flow: attachment upload
|
||||
|
||||
Uploads use a bounded streaming pipeline:
|
||||
|
||||
1. authenticate and authorize;
|
||||
2. stream to a quarantined temporary file with a hard size limit;
|
||||
3. calculate SHA-256;
|
||||
4. inspect signature and type;
|
||||
5. reject active/unsafe inline behavior;
|
||||
6. atomically move to content-addressed storage;
|
||||
7. commit blob/reference metadata;
|
||||
8. schedule safe preview generation where supported;
|
||||
9. remove temporary data on failure.
|
||||
|
||||
No ordinary upload is executed or automatically extracted.
|
||||
|
||||
## Data flow: import
|
||||
|
||||
1. Discover source in read-only mode.
|
||||
2. Fingerprint all relevant source items.
|
||||
3. Select a versioned adapter.
|
||||
4. Produce a preflight plan with conflicts/ambiguities.
|
||||
5. Persist the plan.
|
||||
6. Execute in bounded transactional batches with import provenance.
|
||||
7. Resolve stable internal relations.
|
||||
8. Validate counts, tree, links and file hashes.
|
||||
9. Re-fingerprint the source.
|
||||
10. Mark complete only when source is unchanged and validation passes.
|
||||
|
||||
## Background jobs
|
||||
|
||||
Use database-backed jobs/leases rather than a mandatory external broker.
|
||||
|
||||
Initial job types:
|
||||
|
||||
- search projection repair;
|
||||
- attachment preview;
|
||||
- orphan blob cleanup;
|
||||
- import execution and validation;
|
||||
- export generation;
|
||||
- backup creation and verification;
|
||||
- retention purge;
|
||||
- outbox dispatch/retention;
|
||||
- integrity scan.
|
||||
|
||||
Jobs require idempotency, bounded retries, backoff, cancellation and administrator-visible
|
||||
status.
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration precedence:
|
||||
|
||||
1. secure mounted secret/file where applicable;
|
||||
2. environment variables;
|
||||
3. `appsettings.Production.json`;
|
||||
4. compiled safe defaults.
|
||||
|
||||
Database credentials and key material are not stored in repository configuration.
|
||||
|
||||
## Future evolution
|
||||
|
||||
Possible later extraction candidates are backup/export workers or an MCP adapter, but only
|
||||
after measured pressure. The domain and API boundaries must not assume extraction is
|
||||
required.
|
||||
Reference in new issue
Block a user