Vault

Document store

Tier: Platform · Status: ✅ Prototyped (spine)

Purpose

Vault stores documents: the bytes, their classification, integrity hash, and the active storage repository that holds them. Engines that need attachments — Registry, Strata, Docket — receive a document_id and create a link. They do not own storage configuration.

Vault is platform infrastructure (alongside Keycloak and the database), not a supervisory engine in the five-tier model.

Scope

Capability	Status
Pluggable repositories (local default, s3, azure)	✅
Properties-driven config (kovent.vault.* + Quarkus extension props)	✅
Document class taxonomy (vault_document_class)	✅ Seeded + maintainable in UI
Store / download / link documents	✅
Platform document catalogue (search, class filter, pagination)	✅
Firm / person linked documents (table + upload dialog)	✅
Drop-zone upload with class + purpose	✅
Read-only active-repository status	✅
GCS / OneDrive repositories	⬜ Deferred
DB-backed storage templates / in-product credentials	⬜ Deferred (nav stubs only)

v1 decisions

Topic	Choice
Repositories	local (default) · s3 · azure — real Quarkus clients; GCS / OneDrive deferred
Selection	kovent.vault.repository + Quarkus @LookupIfProperty on VaultStorageRepository
Config	Properties for bucket / folder / local root — not DB-backed backends yet
S3	quarkus-amazon-s3 + sync URL client; locators s3://bucket/key
Azure	quarkus-azure-storage-blob; enable with quarkus.azure.storage.blob.enabled=true; locators azure://container/blob
Classification	vault_document_class (what the file is) vs link document_purpose (why attached)
UI	Vault → Documents (platform catalogue) · Document classes · firm/person Documents tab

Recorded as KD-014.

kovent.vault.repository=local
kovent.vault.bucket=
kovent.vault.folder=
kovent.vault.local.root-path=target/kovent-vault

Cloud credentials use Quarkus extension properties (quarkus.s3.*, quarkus.azure.storage.blob.*). Dev Services for S3/Azure are off by default — point S3 at LocalStack (or real AWS) yourself when testing. In-product “Storage templates” / “Keys & credentials” remain coming-soon stubs until config moves to the database.

LocalStack (S3) smoke

KOVENT_VAULT_REPOSITORY=s3
KOVENT_VAULT_BUCKET=kovent-vault
QUARKUS_S3_ENDPOINT_OVERRIDE=http://localhost:4566
QUARKUS_S3_PATH_STYLE_ACCESS=true
QUARKUS_S3_AWS_CREDENTIALS_STATIC_PROVIDER_ACCESS_KEY_ID=test
QUARKUS_S3_AWS_CREDENTIALS_STATIC_PROVIDER_SECRET_ACCESS_KEY=test

Azure smoke

KOVENT_VAULT_REPOSITORY=azure
KOVENT_VAULT_BUCKET=kovent-vault
QUARKUS_AZURE_STORAGE_BLOB_ENABLED=true
QUARKUS_AZURE_STORAGE_BLOB_CONNECTION_STRING=...

Model

Entity	Role
vault_document	Filename, mime, size, hash, document_class_id, storage backend code, locator
vault_document_class	Maintainable taxonomy (seeded: IDENTITY_DOCUMENT, LICENCE_CERTIFICATE, RETURN_ATTACHMENT, …)
vault_document_link	Attaches a document to another record (linked_type + linked_id) with a purpose
VaultStorageRepository	SPI: LocalVaultStorage (default), S3VaultStorage, AzureVaultStorage

erDiagram
    VAULT_DOCUMENT }o--|| VAULT_DOCUMENT_CLASS : "classified as"
    VAULT_DOCUMENT ||--o{ VAULT_DOCUMENT_LINK : "attached via"

    VAULT_DOCUMENT {
        uuid id PK
        string original_filename
        string mime_type
        bigint byte_size
        string content_hash
        uuid document_class_id FK
        string storage_backend
        string storage_uri
    }
    VAULT_DOCUMENT_CLASS {
        uuid id PK
        string code UK
        string name
        boolean is_active
        int sort_order
    }
    VAULT_DOCUMENT_LINK {
        uuid id PK
        uuid document_id FK
        string linked_type
        uuid linked_id
        string document_purpose
    }

Callers upload bytes with a documentClassId. Vault returns document_id. Optional link carries document_purpose. Changing repository is a properties / deployment change for v1, not a per-document consumer change.

API (spine)

Method	Path	Role
GET	/api/vault/status	Active repository (non-secret)
GET	/api/vault/document-classes	List classes (activeOnly)
POST / PUT	/api/vault/document-classes	Maintain taxonomy
GET	/api/vault/documents	Platform catalogue (q, documentClassId)
POST	/api/vault/documents	Multipart store (file, documentClassId)
GET	/api/vault/documents/{id}/content	Download bytes
POST	/api/vault/documents/{id}/links	Attach to a record
GET	/api/vault/links	Links for linkedType + linkedId

Operator UI

Surface	Behaviour
Vault → Documents	All platform documents; search; class filter; pagination; Upload opens drop-zone dialog (class + purpose + link target required)
Vault → Document classes	Maintain taxonomy (same register pattern as condition types)
Firm / person → Documents	Linked documents table; search; class filter; pagination; Upload auto-links to that party with class + purpose
Vault → Storage templates / Keys	Coming soon — v1 stays on properties

Owns

• Document metadata, content hash, mime type
• Document class taxonomy
• Active storage SPI and locators
• Polymorphic document links
• Read-only vault status for operators

Does not own

• Licensing application checklists and “criteria met” for required application documents
• Business rules for which attachments a return template requires — return templates and Assay
• Retention / legal-hold policy (owned with Seal / Docket evidence semantics when specified)
• DB-backed multi-tenant storage catalogues (later)

Consumers

Consumer	Use
Registry	Documents linked to parties (firm / person records)
Strata	Supporting documents on submissions
Docket	Case evidence
Assay	Attachment completeness against return templates

Related

• KD-014
• Registry
• Licensing
• Strata
• Assay