feat: establish portable platform foundations

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

.gitattributes

@@ -1,6 +1,7 @@
 * text=auto
 .gitattributes text eol=lf
 .gitignore text eol=lf
+.prettierignore text eol=lf
 *.sha256 text eol=lf
 *.md text eol=lf
 *.json text eol=lf
@@ -10,13 +11,15 @@
 *.toml text eol=lf
 *.ts text eol=lf
 *.tsx text eol=lf
+*.mjs text eol=lf
 *.kt text eol=lf
 *.kts text eol=lf
 *.py text eol=lf
 *.ps1 text eol=crlf
 *.bat text eol=crlf
 *.cmd text eol=crlf
 *.png binary
+*.ico binary
 *.jpg binary
 *.jpeg binary
 *.gif binary

.gitignore

@@ -30,6 +30,7 @@ htmlcov/
 
 # Gradle and Android
 .gradle/
+.kotlin/
 **/build/
 local.properties
 *.apk

.node-version

@@ -0,0 +1 @@
+24.17.0

.prettierignore

@@ -0,0 +1,9 @@
+.github/workflows/README.md
+.superpowers/
+AGENTS.md
+README.md
+docs/
+**/README.md
+pnpm-lock.yaml
+packages/contracts/generated/
+packages/design-tokens/brand/derivatives.json

.tool-versions

@@ -0,0 +1,6 @@
+nodejs 24.17.0
+pnpm 11.18.0
+python 3.13.0
+java temurin-21
+postgres 17
+redis 7.4

docs/plans/000-platform-program.md

@@ -0,0 +1,61 @@
+# DataBreeze Platform Implementation Program
+
+**Status:** Approved<br>
+**Implementation branch:** `dev` through short-lived `feat/*` and `fix/*` branches<br>
+**Primary specifications:** `docs/product/`, `docs/architecture/`, `docs/specs/`, and accepted ADRs
+
+## Goal
+
+Implement DataBreeze as one Vietnamese-first, local-first business data platform across Web, Windows Desktop, and Android. The platform turns user-controlled files, documents, captures, and governed datasets into traceable jobs, evidence, reviews, approvals, reports, and safe actions without depending on restricted marketplace APIs.
+
+The program covers all 611 normative requirements. P0 requirements are release gates, P1 requirements complete the generally available capability, and P2 requirements are preserved as extension seams but are not scheduled for the first release.
+
+## Locked decisions
+
+- One clean monorepo with independently releasable deployables.
+- TypeScript for Web, Desktop, shared packages, and the NestJS/Fastify control plane.
+- Native Kotlin/Compose for Android and Python for the shared processing engine.
+- PostgreSQL is authoritative; S3-compatible storage holds cloud bytes; Redis is non-authoritative.
+- Local, Hybrid, and Cloud data modes remain visible and enforceable throughout every workflow.
+- First usable release is a private dogfood alpha built on the full multi-tenant architecture.
+- The first cross-platform workflow is Folder Autopilot plus Spreadsheet Auditor.
+- Core value does not require Shopee, TikTok Shop, accounting, advertising, or ERP partnerships.
+- AWS Singapore is the first hosted target through portable containers and OpenTofu.
+- The existing DataBreeze name and canonical logo files are retained without redrawing.
+
+## Delivery program
+
+| Phase | Child plan | Release gate |
+|---|---|---|
+| 0 | `010-engineering-foundation.md` | Toolchains, contracts, brand, deployable shells, local dependencies, and CI build reproducibly. |
+| 1A | `020-identity-audit-entitlements.md` | IAM, AUD, and provider-independent BUA foundations pass tenant and security gates. |
+| 1B | `030-artifacts-datasets-evidence.md` | IAE and DSM provide immutable artifacts, evidence, datasets, schemas, rules, and mappings. |
+| 1C | `040-jobs-processing-approvals.md` | JRA, admission coordination, cloud workers, and the local engine execute signed typed jobs. |
+| 1D | `050-devices-sync-offline.md` | Desktop and Android enroll, sync, recover, conflict, and revoke safely. |
+| 1E | `060-collaboration-integrations.md` | NCO and INT provide governed collaboration, notifications, API keys, and webhooks. |
+| 2 | `070-dogfood-folder-spreadsheet.md` | One spreadsheet-folder workflow crosses all three applications and preserves the original. |
+| 3 | `1xx-wave-1-*.md` | Folder Autopilot, Spreadsheet Auditor, Quote Intelligence, and Operations Capture. |
+| 4 | `2xx-wave-2-*.md` | Invoice Leak Detector, Client Report Factory, and Private Data Analyst. |
+| 5 | `3xx-wave-3-*.md` | Migration Ready, Data Quality Guard, and Embedded Importer. |
+| 6 | `400-production-readiness.md` | Signing, restoration, scaling, security, support, and progressive releases pass. |
+
+Child plans are written and approved before their product slice begins. Each names exact requirement IDs, paths, contract changes, migrations, tests, telemetry, failure behavior, rollback, and intentionally deferred requirements.
+
+## Branch, commit, and review policy
+
+- `main` contains stable releases. `dev` is the integration branch.
+- New capabilities use `feat/<name>`; corrections use `fix/<name>`; operational and documentation work use conventional prefixes when more accurate.
+- Commit one coherent tested unit at a time. Do not combine unrelated applications or domains merely to reduce commit count.
+- Pull requests target `dev`, normally contain 30–50 commits, and must not exceed 70 commits.
+- Invoke CodeRabbit once per pull request after the branch is ready for review. Validate every comment against the specifications and tests; fix valid findings and document why invalid findings are not applied.
+- Promote `dev` to `main` only through a separate release pull request after the relevant production gates pass.
+
+## Cross-cutting definition of done
+
+- Requirement-to-task-to-test traceability is complete.
+- Generated TypeScript, Kotlin, and Python contracts agree.
+- Tenant scope, authorization, data mode, evidence, approval, audit, and retention rules cannot be bypassed.
+- Vietnamese and English user-facing copy are complete for the delivered slice.
+- Relevant unit, integration, contract, end-to-end, security, accessibility, recovery, and performance tests pass.
+- Migrations, observability, operations, rollback, and release evidence are present.
+- No critical- or high-severity security finding remains unresolved for a production release.

docs/plans/010-engineering-foundation.md

@@ -0,0 +1,129 @@
+# Engineering Foundation Implementation Plan
+
+**Status:** Approved<br>
+**Parent:** `000-platform-program.md`<br>
+**Branch:** `feat/platform-foundation`
+
+## Outcome
+
+Create the reproducible monorepo foundation required by Stage 0 of the product roadmap. This plan introduces no customer workflow or production data migration. It establishes tested build, contract, brand, application-shell, infrastructure, observability, security, and delivery boundaries on which every normative requirement will depend.
+
+## Global constraints
+
+- Node.js 24 LTS, pnpm/Corepack, Turborepo, strict TypeScript, Python 3.13 through `uv`, JDK 21, PostgreSQL 17, and Redis 7.4 are pinned by repository-controlled configuration.
+- Web and Desktop may share React packages. Android consumes generated contracts and tokens but remains native Kotlin/Compose.
+- Clients never import service implementation packages.
+- No client or processing worker receives database credentials.
+- Generated artifacts must be reproducible and checked for drift in CI.
+- New behavior follows test-first red/green/refactor development.
+- Canonical legacy brand sources retain their exact bytes and documented SHA-256 values.
+- No secret, credential, runtime database, customer file, generated report, signing key, APK, or installer is committed.
+
+## Tasks
+
+### Task 1: Root workspace and runtime pins
+
+Create the root pnpm/Turborepo workspace, package scripts, TypeScript base configurations, editor-neutral formatting/linting configuration, runtime-version files, and package-manager pin. Add a smoke test that validates workspace package discovery and runtime policy. Commit as `chore(repo): bootstrap the monorepo toolchain`.
+
+### Task 2: Repository dependency-boundary enforcement
+
+Add executable checks that prevent clients from importing service implementations, prevent feature-to-feature persistence imports, and require public package exports. Cover allowed and rejected fixture graphs before enabling the check in root `lint`. Commit as `test(architecture): enforce repository dependency boundaries`.
+
+### Task 3: Requirement traceability tooling
+
+Implement a read-only parser that discovers all stable requirement IDs, rejects duplicates or malformed priorities, and produces a deterministic traceability index. Add fixtures for duplicates, gaps, and valid documents, then generate the initial index for all 611 requirements. Commit as `feat(traceability): index normative requirements`.
+
+### Task 4: Contract source layout and base envelopes
+
+Create versioned JSON Schemas for UUID identifiers, UTC timestamps, revisions, tenant scope, correlation metadata, RFC 7807-compatible problems, idempotent commands, cursor pages, and the canonical event envelope. Test valid and invalid examples with a standards-compliant validator. Commit as `feat(contracts): define shared protocol envelopes`.
+
+### Task 5: Cross-language contract generation
+
+Create deterministic generators and generated-package layouts for TypeScript, Kotlin, and Python. Add a drift command that regenerates into a temporary directory and byte-compares outputs. Commit as `feat(contracts): generate typescript kotlin and python models`.
+
+### Task 6: Contract compatibility and fixture package
+
+Add schema compatibility policy, shared valid/invalid protocol fixtures, and consumer tests proving all three generated model sets accept and reject equivalent payloads. Commit as `test(contracts): enforce cross-language parity`.
+
+### Task 7: Permission and tenant-scope primitives
+
+Create versioned permission constants, the six initial role bundles, tenant-scope value objects, and deny-by-default helpers without implementing IAM persistence. Test narrowing and cross-scope rejection. Link IAM-001 through IAM-004, IAM-009, and IAM-019 as partial foundation coverage. Commit as `feat(permissions): add scoped authorization primitives`.
+
+### Task 8: Configuration and provider ports
+
+Create typed configuration loading with explicit development/test/preview/staging/production profiles and ports for object storage, email, push, OCR, AI, payments, telemetry, and secrets. Reject missing production configuration and unknown keys. Commit as `feat(config): define portable provider boundaries`.
+
+### Task 9: Vietnamese and English terminology package
+
+Create the canonical `vi-VN` and `en` message catalogs, locale negotiation, formatting helpers, and completeness tests. Vietnamese is the default and missing keys fail CI. Commit as `feat(i18n): establish complete bilingual catalogs`.
+
+### Task 10: Immutable legacy brand sources
+
+Copy the three canonical named logo files into the design-system source directory. Add a manifest containing dimensions, intended use, and the approved SHA-256 hashes, plus a checksum test that fails on byte changes. Commit as `feat(brand): preserve canonical databreeze assets`.
+
+### Task 11: Reproducible brand derivatives
+
+Build a deterministic image pipeline for Web favicons/social assets, Desktop icons, and Android launcher/notification sources. Preserve aspect ratio, colors, and safe zones; prohibit wordmark duplication. Add dimension, checksum, and visual-regression fixtures. Commit as `feat(brand): generate platform logo derivatives`.
+
+### Task 12: Design tokens and accessible UI primitives
+
+Create shared color, typography, spacing, motion, focus, status, and logo-usage tokens. Export TypeScript/CSS and generated Android resources. Add contrast, reduced-motion, and generation-drift tests. Commit as `feat(design-system): add shared accessible tokens`.
+
+### Task 13: Web application shell
+
+Create the React/Vite shell with React Router, TanStack Query, Tailwind, accessible primitives, bilingual routing/layout, error boundaries, and placeholder authenticated navigation. Add Vitest/Testing Library and Playwright smoke coverage. Commit as `feat(web): create the governed workspace shell`.
+
+### Task 14: Control-plane API shell
+
+Create the NestJS/Fastify modular-monolith shell, health/readiness endpoints, request correlation, RFC 7807 errors, structured validation, OpenAPI generation, Prisma multi-schema layout, and domain boundary structure. Test boot, validation, and error behavior. Commit as `feat(api): create the modular control plane shell`.
+
+### Task 15: Windows Desktop security shell
+
+Create the Electron/React/Vite shell with sandboxing, context isolation, disabled Node integration, restrictive navigation/CSP, a versioned allowlisted preload API, local-state abstraction, and sidecar lifecycle port. Add security preference and IPC rejection tests. Link DSK-001, DSK-002, and DSK-008 as partial coverage. Commit as `feat(desktop): create the secure local agent shell`.
+
+### Task 16: Python engine shell
+
+Create the `uv` project, Pydantic protocol models, versioned action-manifest registry, deterministic handler interface, framed JSON-RPC entry point, cloud-worker entry point, Ruff/type/pytest configuration, and a test processor. Test malformed frames, unsupported actions, deterministic output, and resource metadata. Commit as `feat(engine): create the typed processing runtime`.
+
+### Task 17: Native Android shell
+
+Create the Gradle wrapper/version catalog and Kotlin/Compose application with bilingual resources, navigation, Room/WorkManager boundaries, Keystore and sync ports, network security configuration, backup exclusions, and baseline unit/instrumentation tests. Commit as `feat(android): create the offline companion shell`.
+
+### Task 18: Local development infrastructure
+
+Create Docker Compose definitions for PostgreSQL 17, Redis 7.4, MinIO, Mailpit, and an OpenTelemetry collector. Add health checks, named development volumes, `.env.example`, initialization scripts without credentials, and a smoke script that validates readiness. Commit as `feat(infra): add portable local dependencies`.
+
+### Task 19: AWS OpenTofu foundation
+
+Create reusable OpenTofu modules and environment compositions for AWS Singapore networking, S3/CloudFront Web hosting, ECS API/worker services, RDS, ElastiCache, KMS, Secrets Manager, logs, and GitHub OIDC. Use safe alpha defaults and explicit production scaling/PITR variables. Validate and lint without applying. Commit as `feat(infra): define the portable aws baseline`.
+
+### Task 20: Shared observability and safe diagnostics
+
+Create structured logging, correlation propagation, OpenTelemetry conventions, safe attribute allowlists, and content-redaction tests shared by API, Web, Desktop, Android, and engine adapters. Commit as `feat(observability): establish content-safe telemetry`.
+
+### Task 21: Continuous integration and supply-chain gates
+
+Create path-aware GitHub Actions for format, lint, typecheck, contract drift, unit/integration tests, builds, SBOM, dependency/license/secret scanning, container scanning, and release provenance. Workflows use least-privilege permissions and no long-lived AWS keys. Commit as `ci: add monorepo quality and security gates`.
+
+### Task 22: Developer workflow and operational foundations
+
+Document clean-checkout setup, branch/commit/PR policy, local services, contract changes, troubleshooting, provider adapters, release channels, and initial deployment/rollback/secret-rotation runbooks. Commit as `docs: document foundation development and operations`.
+
+### Task 23: Clean-checkout verification and release evidence
+
+Run the complete root verification from a clean worktree, build each deployable, regenerate contracts/assets, validate Compose and OpenTofu, and record requirement/test/build evidence without committing runtime artifacts. Fix only failures within this plan. Commit any necessary corrections in narrowly scoped `fix(...)` commits, then prepare the pull request to `dev`.
+
+## Acceptance and rollback
+
+- One documented bootstrap path prepares every available toolchain.
+- Root format, lint, typecheck, contract, unit, integration, and build commands exit successfully.
+- Web, API, Desktop, engine, and Android empty deployables build independently.
+- Local dependencies reach healthy state and can be torn down without deleting user-owned files.
+- Contract and brand regeneration is reproducible and drift-free.
+- CI uses synthetic fixtures only and emits no secrets or customer content.
+- Every task is a separate rollback unit. Reverting an application shell must not remove shared contracts used by another completed shell.
+- AWS resources are not applied by this plan; rollback is therefore repository reversion plus removal of local disposable containers/volumes when explicitly requested.
+
+## Deferred requirements
+
+All business workflows and persistent IAM/IAE/DSM/JRA/DSO/NCO/INT/BUA/AUD behavior beyond the explicitly named primitives remain deferred to the subsequent child plans. A passing engineering-foundation build does not mark those requirements implemented.