# ItWorx Knowledge Hub

A self-hosted knowledge, documentation and project-intelligence platform for people
who want the speed of Markdown with the safety of revisions, permissions and verified
backups.

Knowledge Hub combines a technical wiki, project dossiers, architecture decisions and
runbooks in one searchable application. It remains fully useful without AI. A scoped
REST API supports external automation, while MCP transport deliberately lives outside
this repository.

## What you can do

- Organize Markdown pages in a fast, hierarchical knowledge tree.
- Search titles, content and tags with PostgreSQL full-text and fuzzy matching.
- Edit safely with private drafts, immutable revisions and explicit conflict handling.
- Upload deduplicated attachments with signature-based type validation.
- Track projects, milestones, updates, architecture decisions and runbook validation.
- Import LeafWiki content through a read-only, preflighted and reversible workflow.
- Create scoped, revocable service-account tokens for the versioned `/api/v1` API.
- Back up the database and attachments together, then verify a clean-target restore.

## Screenshots

These captures come from a local instance populated with synthetic demo data.

![Synthetic workspace dashboard](docs/assets/screenshots/02-dashboard.png)

![Synthetic Markdown knowledge workspace](docs/assets/screenshots/03-knowledge.png)

## Quick start

Requirements: Docker with Compose, Node.js 24 and Corepack.

```bash
cp .env.example .env
# Set a strong, unique POSTGRES_PASSWORD in .env.
node scripts/doctor.mjs
docker compose up --build -d
```

Open `http://localhost:1240` and complete the one-time owner setup. The default stack
contains one application container and one PostgreSQL container; PostgreSQL is not
published to the host.

For a production deployment, terminate TLS at a trusted reverse proxy, use mounted
secrets, persist every documented data volume and test restore before relying on a
backup. Start from the reviewed [Docker Compose configuration](docker-compose.yml) and
the [backup/restore guide](docs/guides/back-ups-herstel-en-unraid-beheer.md).

## Architecture

```text
Browser or scoped API client
            |
         HTTPS
            |
  ASP.NET Core + React
            |
        PostgreSQL
            |
 attachments / backups
```

The backend is a modular monolith with separate Domain, Application, Contracts,
Infrastructure and API projects. React is built into the production image. Markdown is
the canonical human-readable content format, PostgreSQL is the transactional source of
truth, and attachments are stored by SHA-256 outside the database.

## Development and verification

```bash
corepack pnpm install --frozen-lockfile
node scripts/verify.mjs --fast
node scripts/verify.mjs --ci
```

The CI gate covers formatting, compilation, static analysis, backend and frontend
tests, OpenAPI consistency and the production image. The release gate adds dependency,
secret and container scans plus the full-scale search proof:

```bash
node scripts/verify.mjs --release
```

Integration tests use real PostgreSQL through Testcontainers. Browser tests exercise
desktop and mobile flows and include automated accessibility checks.

## API and automation

The OpenAPI contract is in [docs/api/openapi.yaml](docs/api/openapi.yaml). External
clients use one-time-display service-account tokens with explicit scopes. Mutating
content routes use ETags and `If-Match`; retryable creates support `Idempotency-Key`.

This repository does not contain an MCP server, shell executor, arbitrary script
runtime or runbook execution engine.

## Security and data safety

- Content is private by default and authorization is enforced server-side.
- Cookie mutations require CSRF protection; API clients use scoped bearer tokens.
- Normal deletion uses trash and retention; permanent purge is an explicit admin act.
- LeafWiki inspection and import never modify the source.
- Restore targets must be clean and are verified against backup manifests and hashes.
- The production container runs non-root with a read-only root filesystem and dropped
  capabilities.

Report vulnerabilities using [SECURITY.md](SECURITY.md). Do not include secrets or real
private knowledge in an issue.

## Project status and limitations

The implemented platform includes the wiki, search, projects, ADRs, runbooks,
attachments, reversible import, scoped API and backup/restore path. Current limitations
include no real-time collaborative editing, no built-in MCP transport, no arbitrary
runbook execution and no public anonymous publishing by default.

Historical delivery and production evidence is retained in the private canonical
repository. The `itworx-knowledge-hub-Public` repository is automatically generated from the curated source boundary after merges to private canonical `main`. The manifest identifies the exact source revision. Private history, real knowledge, operational evidence and internal Actions remain excluded.

## Contributing and license

See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. The project remains proprietary under [LICENSE](LICENSE). Public visibility grants no additional redistribution or open-source rights; third-party dependencies retain their own terms.