itworx-knowledge-hub-Public/docs/06-system-architecture.md

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

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

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

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:

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

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.