ViCLAS-MVR (Internal MVP)

ViCLAS-style internal application for MVR Bulgaria with SATP-driven case capture, search, deterministic linkage analysis, reporting, and enterprise integration adapter boundaries.

Important Boundaries

• No production database is created or managed by this project.
• Production integrations are externalized through adapters (IdP/SSO, data API, file storage, SIEM, secrets/cert sources).
• Local demo mode uses test-only local adapters and synthetic data.
• The supported runtime target is a Windows desktop program hosted by WPF + WebView2.
• Mobile and tablet workflows are out of scope and unsupported.

Monorepo Layout

• apps/api - Fastify backend (RBAC, audit, case workflow, search, linkage, reports)
• apps/web - React + TypeScript frontend
• apps/desktop-host - .NET 8 WPF host embedding WebView2 for Windows desktop runtime
• packages/shared - shared contracts/types
• packages/linkage-core - deterministic feature extraction + scoring logic
• packages/questionnaire-model - generated SATP model loader
• scripts/extract_satp.py - SATP XLS extraction to JSON model
• scripts/seed-synthetic-data.mjs - synthetic demo data generator
• docs/ - threat model, configuration, handover docs

Local Setup

1. Install dependencies:
   • pnpm install
2. Install Python dependencies (SATP extractor):
   • python -m pip install -r scripts/requirements.txt
3. Generate SATP model:
   • pnpm satp:extract
4. Generate synthetic dataset:
   • pnpm seed

Run Local Demo

1. Start API:
   • pnpm --filter @viclas/api dev
2. Start Web UI:
   • pnpm --filter @viclas/web dev
3. Open app:
   • http://localhost:5173
4. Login using demo users:
   • investigator, coordinator, analyst, supervisor, admin

The browser dev server is for local development only. The intended operator surface is the packaged Windows desktop host, not a mobile browser workflow.

Verification Commands

• pnpm lint
• pnpm typecheck
• pnpm test
• pnpm build

Source of Truth

• Current-state policy and authoritative file roles: docs/source-of-truth.md
• Current snapshot: STATE.yaml
• Session-by-session evidence: LOG.md
• Curated change summary: CHANGELOG.md
• Long-memory continuity: TIME_CAPSULE.md
• Historical redirect only: MEMORY.md

Desktop Packaging (Windows)

• Build desktop runtime inputs (web/api/host): pnpm desktop:build
• Produce setup EXE + MSI artifacts plus independent first-build snapshot for reproducibility comparison: pnpm desktop:package
• Verify generated packaging output hashes and hardening flags: pnpm desktop:package:check
• Validate generated manifest against packaging contract rules: pnpm desktop:contract:check
• Verify reproducibility hash contract from release artifacts: pnpm release:repro:check
• Validate handover runbook checklist completeness: pnpm release:runbooks:check
• Run full release gate suite (contract + hashes + signature report + reproducibility + SBOM/provenance + runbooks): pnpm release:gates
• Run signed-artifact release gate profile only when release signing infrastructure is available: pnpm release:gates:signed
• Run desktop startup smoke flow (API health + login + case creation): pnpm desktop:smoke
• Run external-navigation denial probe: pnpm desktop:ipc-denial
• Primary packaging outputs are written to apps/desktop-host/dist/release; first-build comparison snapshot outputs are written to apps/desktop-host/dist/release-first
• Local/dev packaging is allowed to produce unsigned candidate artifacts under deferred release-signing mode. Do not claim a signed release unless pnpm release:gates:signed has passed.
• Default runtime distribution target is Evergreen WebView2; restricted/offline endpoint rollout should use the standalone Evergreen installer path documented in the desktop rollout runbook.

Core Demo Flow

1. Create draft case in Cases.
2. Open case workspace, fill SATP sections, save/autosave.
3. Upload attachment and optionally seal with reason.
4. Submit case.
5. Run basic/advanced search.
6. Run link analysis and set analyst labels.
7. Open reports and export CSV/PDF/XLSX demo outputs.

Security Fundamentals Included

• Server-side RBAC permission checks
• Audit events for key actions (Auth.Login, Case.*, Attachment.*, Search.Run, LinkAnalysis.*, Report.Export)
• Attachment controls: MIME allowlist, size limit, antivirus hook placeholder
• Adapter boundaries for SSO, storage, SIEM, and secrets

Notes

• SATP extraction is heuristic and emits ambiguity notes for manual normalization.
• Blueprint remains the priority source where interpretation conflicts may arise.

Compliance

• Engineering compliance charter (retention/audit/policy placeholders for MVR sign-off): docs/compliance.md
• International ViCLAS baseline for BG requirement alignment: docs/handover/viclas-international-baseline-2026-02-25.md
• Active project continuity file: TIME_CAPSULE.md