# Integrinow DMS — Wiring and Coding Standards

This document walks through the "House Style" checklist (code style /
communication style / outreach specifics) and states, point by point, what
this project **actually does** — not the generic template, but what's true
of this codebase today, verified against the code. Where a generic rule
doesn't apply here, that's said explicitly rather than pretended.

## Code style

- **Python version / dependencies.** Python 3.12, but this is **not**
  stdlib-first — `requirements.txt` pulls in Flask, SQLAlchemy, Celery,
  `hvac` (Vault client), `boto3`/`google-cloud-storage`/`azure-storage-blob`
  (multi-cloud backup), `clamd`, `bcrypt`, `python-magic`. That's the
  correct call here: this app's job (RBAC web app + envelope encryption +
  malware scanning + multi-cloud backup) is exactly what those libraries are
  for, and hand-rolling S3/GCS/Azure clients or a JWT/session layer would be
  the actual risk (self-written crypto/auth glue is where security bugs
  live). New dependencies still get flagged in commit messages/PR
  descriptions when added, same spirit as the general rule — just without
  the stdlib-only constraint.

- **File layout.** Config is centralized in `app/config.py` as a single
  `Config` class reading from `os.environ` (fails loudly with `KeyError` if
  a required var like `DATABASE_URL` or `VAULT_ADDR` is missing — no silent
  defaults on anything security-relevant). Paths that need to be absolute
  (the integrity manifest, the local backup dir) are derived from
  `os.path.dirname(os.path.abspath(__file__))`, not hardcoded strings.
  Network calls that can hang have explicit timeouts (e.g.
  `app/services/av_scan.py:22` — `clamd.ClamdNetworkSocket(..., timeout=30)`).
  There are **no bare `except: pass`** anywhere in `app/` or `scripts/` —
  every `except Exception as exc` block either logs and re-raises, logs and
  returns a clear failure state, or (in `app/tasks.py`) marks the Celery task
  failed so it surfaces in Flower/logs instead of disappearing silently.

- **State.** Not JSON-on-disk with `flock` — the durable state (documents,
  users, roles, workflow status) lives in Postgres via SQLAlchemy, because
  this is a multi-worker, multi-container app (Flask + Celery both write
  concurrently) where file-level locking doesn't generalize across hosts.
  The one place a "chain" needs the same tamper-evidence property a
  JSON-ledger would give you — the audit log — uses a **hash chain stored
  as Postgres rows** (`app/services/audit.py`): each entry's `entry_hash`
  covers a canonical JSON encoding of the row plus the previous row's hash,
  and appends are serialized with a Postgres advisory transaction lock
  (`pg_advisory_xact_lock`) so concurrent Celery workers can't fork the
  chain. `GET /audit/verify` walks the whole chain and reports the first
  broken link, if any.

- **LLM calls.** None. This project has no LLM-routed logic anywhere in the
  pipeline — malware detection is ClamAV, workflow state transitions are
  plain code, nothing here is generated or decided by a model at runtime.
  This whole bullet (router/fallback-ladder/lenient-parse) is not
  applicable to this codebase.

- **Patches to existing files.** No anchor-asserted patch-script tooling is
  used in this repo — changes are made directly to source files and go
  through the source-integrity manifest instead (`scripts/generate_integrity_manifest.py`
  fingerprints every tracked file and Vault-signs the list at release time;
  `app/services/integrity.py` re-checks it on every boot and refuses to
  start if a `.py`/template/shell file doesn't match). That's this project's
  equivalent safety net for "did the file actually change the way I think it
  did" — enforced at startup, not at patch-apply time.

- **Shell/cron.** This is a real deviation from the generic rule, worth
  stating plainly rather than glossing over: `scripts/nightly_backup.sh`,
  `scripts/vault_unseal.sh`, and `start-system.sh` all use
  `#!/usr/bin/env bash` and `source` (not `#!/bin/sh` + `.`), because they
  rely on bash-only features (`set -a`/`set +a` for env export, arrays in
  `start-system.sh`). They're not written to be dash-safe. If POSIX-`sh`
  portability is ever required for this project, that's a real change to
  make, not something already true today. What *is* true: absolute paths
  (`cd "$(dirname "$0")/.."`), `set -euo pipefail` on every script, and
  cron invocation only for `nightly_backup.sh` (see `crontab -l` — no
  `pgrep -f` self-matching patterns in use here).

- **Comments.** Matches the general rule well already: comments in this
  codebase explain *why*, not *what* — e.g. the advisory-lock comment in
  `audit.py` explains the race it prevents, the `Config` docstring for
  `BACKUP_REMOTE_TARGETS` explains the multi-cloud fallback semantics, the
  `S3_PUBLIC_ENDPOINT_URL` comment explains the presigned-URL bug it exists
  to avoid. Module/class-level docstrings state what the file is for
  (`app/services/audit.py`'s module docstring is one line: what it is, and a
  pointer to the fuller rationale).

- **Verification is part of the deliverable.** This one *is* a firm existing
  practice: README.md documents the exact one-liners
  (`python3 -m pytest tests/ --ignore=tests/e2e -v` for unit/integration,
  `python3 -m pytest tests/e2e/ -v --browser chromium` for the real-browser
  journey), and `tests/` covers RBAC, crypto, the audit chain (including a
  concurrency test — `test_audit_concurrency.py` — for the exact race the
  advisory lock prevents), the workflow state machine, object-lock/WORM
  backup behavior, and behavior when Vault is sealed. `GET /audit/verify` is
  itself a runtime artifact-check endpoint, not just a test.

## Communication style

These are documentation/process conventions, not code — restated here as
they apply to how this project's docs (`README.md`, `technical-spec.md`,
`development-status.md`) are written and should keep being written:

- Lead sentences state the outcome, not the setup (see this repo's own
  `.env.example` comments — each one leads with the consequence of getting
  a var wrong, e.g. the `S3_PUBLIC_ENDPOINT_URL` comment leads with "uploads
  will fail for every real client," not "this is an optional endpoint
  setting").
- Plain English, exact file paths and HTTP codes — README.md's route list
  gives exact paths (`GET /audit/log`) and status semantics, not
  paraphrases.
- Vault root-token / unseal-key handling is called out with explicit
  "done — do not re-do" framing in `.env.example` (revoke-and-delete
  instructions right next to `VAULT_ROOT_TOKEN`).
- No invented terminology — Vault/KEK/DEK/transit-engine terms are Vault's
  own vocabulary, glossed on first use in README rather than renamed.

## Outreach / creative specifics

Not applicable to this project. There's no humanizer pass, no diffusion/video
image generation, no client-facing creative pricing tiers anywhere in this
codebase — this section of the generic house-style doc describes a different
kind of project entirely and is included here only for completeness (so this
file is a full point-by-point pass over the source document, not a partial
one).