Skip to content
Oxydian edited this page Nov 12, 2026 · 2 revisions

🌐 Atlas Logistics — Knowledge Base & Architecture Wiki

Welcome to the official technical Wiki for Atlas Logistics, an enterprise-grade, event-driven multimodal freight forwarding operating system built with high-velocity TypeScript, Fastify, Drizzle ORM, SQLite (WAL mode), and React 19.


🏛️ Core Architecture Pillars

Pillar Technical Implementation Operational Guarantee
Zero-Cost & Offline-First Embedded SQLite in WAL mode (PRAGMA journal_mode=WAL;) with enforced foreign keys (PRAGMA foreign_keys = ON;). Operates 100% autonomously without external cloud database subscriptions or persistent internet connectivity.
Event Sourcing & Outbox Transactional Outbox pattern (scmOutboxMessages / outboxBus) and idempotent message consumption (scmInboxProcessedMessages). Guarantees atomic aggregate persistence and enables trivial offline-to-central synchronization via append-only event logs.
Zero Mocks Standard All UI modules, Fastify APIs, and test suites run against real relational SQLite tables. No in-memory fake buttons. Eliminates drift between dev, staging, and production; real constraints tested from day one.
Strict File Governance Documents stored as relative disk paths with cryptographic SHA-256 hashes (DOCS_ROOT); zero BLOBs in SQLite. Fast, crash-resilient document storage with automated disk garbage collection (clean:documents).
Hot In-Memory Caching UN/LOCODE global port registry indexed in a Prefix Trie and LRU cache with Write-Through mutations. Sub-millisecond geographic autocomplete in hot RAM without requiring server or node process restarts.

🧭 Navigation by Diátaxis Framework

This knowledge base follows the Diátaxis Documentation Framework, categorizing all project knowledge into four distinct quadrants:

quadrantChart
    title Diátaxis Documentation Quadrants
    x-axis Practical Knowledge --> Theoretical Knowledge
    y-axis Learning-Oriented --> Problem-Solving
    "1. Tutorials": [0.2, 0.8]
    "2. How-To Runbooks": [0.2, 0.2]
    "4. Architecture & ADRs": [0.8, 0.8]
    "3. Technical Reference": [0.8, 0.2]
Loading

1. 🎓 Getting Started & Tutorials

  • Local Development Guide — Quickstart walkthrough for configuring Node.js, pnpm, environment variables, SQLite database, and running backend & frontend services.

2. 🛠️ How-To Guides & Operational Runbooks

  • Zero Cost & Offline Topology — How the offline architecture operates, including SQLite WAL mode, local document storage, Write-Through caching, and event sync.
  • Backup & Storage Governance — Database ACID backups via native SQLite VACUUM INTO and disk garbage collection routines.

3. 📖 Technical Reference & Regulatory Standards

4. 🏛️ Architecture & Architectural Decision Records

  • Architecture Overview — High-level platform design, CQRS BFF projections, Bounded Contexts, and micro-frontend architecture.
  • ADR Index — Full register of all 21 Architectural Decision Records detailing decisions from initial pnpm standardization to external data governance.

📦 Monorepo Quick Links

  • Main Repository: xpallares1987-ai/Atlas-Logistics
  • Backend Fastify Core: src/ (Routes, SCM Kernel, Drizzle Relational Schema)
  • Frontend Packages: packages/frontend, packages/dashboard, packages/rate-comparer, packages/bpmn-modeler, packages/warehouse-ops
  • Shared Libraries: packages/shared (Zod validation schemas, UN/LOCODE trie, DTOs) & packages/ui (Design system)

Clone this wiki locally