Appearance
Architecture Decision Records (ADR) Log
This decision log documents all architectural and technical design decisions across TruthGuard, recording the chosen solution, evaluated alternatives, deciding factors, and conditions under which the decision should be revisited.
Master Architecture Decisions Table
| Decision # | Architectural Decision | Chosen Option | Alternatives Considered | Deciding Factors | Trade-Off Accepted | Revisit When |
|---|---|---|---|---|---|---|
| ADR-01 | Frontend Micro-Frontend Topology | Port-based Federated Hub (FeatureEmbed.tsx) | Monolithic SPA, Webpack Module Federation, Single-SPA | Complete failure isolation; independent local development cycles; zero shared dependency lock-in. | Duplicate browser memory when opening multiple modules simultaneously. | Modules need to share large in-memory WebGL frame buffers directly. |
| ADR-02 | Client-Side Binary Forensics | Native Web Crypto API (window.crypto.subtle) | CryptoJS, Node.js server crypto, js-sha256 | Zero bundle weight; compiled C++ execution; evidentiary privacy (media never leaves analyst RAM). | Requires secure HTTPS context or localhost origin. | Complex SHA-3 or post-quantum algorithms are mandated by federal law. |
| ADR-03 | EXIF Header Parsing Engine | exifr binary parser | exif-js, piexifjs, Sharp (server-side) | Slices and reads only initial header chunks (~3ms parse time); full support for modern XMP and GPS tags. | Images stripped of EXIF (e.g., social media downloads) require heuristic fallback. | Server-side video metadata extraction across petabyte archives is required. |
| ADR-04 | State Management for Custody Drive | Zustand (useMediaVaultStore) | Redux Toolkit, React Context, Jotai, MobX | 1.1 KB footprint; provider-less architecture; decoupled atomic selector updates during rapid upload progress. | Lacks enterprise Redux time-travel action replay. | The application scales to hundreds of complex inter-dependent server cache mutations. |
| ADR-05 | Cloud Backend & Database Tier | Supabase Cloud (PostgreSQL + GoTrue) | Custom MERN (Express + MongoDB), AWS Amplify, Firebase | Built-in Row Level Security (RLS); PostgreSQL relational ACID guarantees; serverless Deno Edge Function hosting. | Relies on third-party cloud infrastructure (mitigated by self-hostable Docker support). | Air-gapped military deployments with zero internet connectivity are required. |
| ADR-06 | AI Inference Strategy | Pre-Trained Models via Serverless Edge Functions | Training custom ML models locally, onnxruntime-web in browser | Zero model training and GPU maintenance cost; instant adaptation to new diffusion architectures; keeps client bundle small. | Ongoing API token inference cost for high-volume text analysis. | The company collects 500,000+ proprietary forensic samples and secures private GPU cluster funding. |
| ADR-07 | Design System & Styling | Tailwind CSS with NVIDIA Dark Palette | Vanilla CSS, CSS Modules, styled-components, Material UI | Compiles down to <15 KB static CSS; zero JavaScript runtime style injection; exact custom hex tokens. | Verbose class strings in JSX templates. | Dynamic user-generated runtime theme creation is required. |
| ADR-08 | Dynamic Service Discovery | Client-Side Port Prober (HEAD / no-cors) | Hardcoded port URLs, Consul, Eureka service registry | Works entirely in client browser without running a separate service discovery server daemon. | Sequential 100ms port probing introduces minor delay on first load. | Micro-frontends are deployed behind a production reverse proxy with path-based routing. |
| ADR-09 | Text Input Length Bound | Client Slicing to 5,000 Characters | Unlimited streaming, multi-chunk batching | Prevents token exhaustion, limits inference latency, and controls cloud billing costs. | Documents exceeding 5,000 characters require manual multi-part submission. | Enterprise customers demand multi-hundred-page book and legal brief auditing. |
| ADR-10 | Evidence Custody Persistence | Browser LocalStorage with Exception Handling | Pure in-memory state, IndexedDB | Instant zero-setup persistence for prototyping across browser reloads; simple JSON serialization. | 5MB browser storage ceiling limits storage to metadata and small files. | Production release requires multi-gigabyte video evidence custody and offline caching. |