From 25d41189a3427291806f50af3964acae4e0bd026 Mon Sep 17 00:00:00 2001 From: Mike Kell Date: Sun, 9 Aug 2026 22:31:22 -0400 Subject: [PATCH] Initial commit: Complete OSAD architecture, specs, and repository structure --- .clinerules | 14 ++ .cursor/rules/00-system-mandates.md | 14 ++ DECISION_LOG.md | 6 + apps/.gitkeep | 0 apps/chronogrid_daemon/.gitkeep | 0 apps/chronogrid_daemon/src/.gitkeep | 0 apps/chronogrid_flutter/.gitkeep | 0 apps/chronogrid_flutter/lib/.gitkeep | 0 apps/chronogrid_flutter/lib/src/.gitkeep | 0 crates/.gitkeep | 0 crates/chronogrid_ai/.gitkeep | 0 crates/chronogrid_ai/src/.gitkeep | 0 crates/chronogrid_core/.gitkeep | 0 crates/chronogrid_core/src/.gitkeep | 0 crates/chronogrid_crypto/.gitkeep | 0 crates/chronogrid_crypto/src/.gitkeep | 0 crates/chronogrid_net/.gitkeep | 0 crates/chronogrid_net/src/.gitkeep | 0 docs/API_CONTRACTS/ffi_bridge_spec.json | 5 + docs/API_CONTRACTS/schema.sql | 20 +++ .../01-OSAD-system-architecture.md | 4 + docs/ARCHITECTURE/02-security-and-crypto.md | 9 + docs/ARCHITECTURE/03-crdt-sync-protocol.md | 5 + docs/UI_UX/01-eisenhower-matrix.md | 4 + docs/UI_UX/02-calendar-timeblocking.md | 4 + docs/UI_UX/03-kanban-gantt-views.md | 4 + docs/WORKFLOWS/01-master-user-story.md | 6 + docs/WORKFLOWS/02-ingestion-pipeline.md | 5 + init_repo.sh | 166 ++++++++++++++++++ scripts/.gitkeep | 0 30 files changed, 266 insertions(+) create mode 100644 .clinerules create mode 100644 .cursor/rules/00-system-mandates.md create mode 100644 DECISION_LOG.md create mode 100644 apps/.gitkeep create mode 100644 apps/chronogrid_daemon/.gitkeep create mode 100644 apps/chronogrid_daemon/src/.gitkeep create mode 100644 apps/chronogrid_flutter/.gitkeep create mode 100644 apps/chronogrid_flutter/lib/.gitkeep create mode 100644 apps/chronogrid_flutter/lib/src/.gitkeep create mode 100644 crates/.gitkeep create mode 100644 crates/chronogrid_ai/.gitkeep create mode 100644 crates/chronogrid_ai/src/.gitkeep create mode 100644 crates/chronogrid_core/.gitkeep create mode 100644 crates/chronogrid_core/src/.gitkeep create mode 100644 crates/chronogrid_crypto/.gitkeep create mode 100644 crates/chronogrid_crypto/src/.gitkeep create mode 100644 crates/chronogrid_net/.gitkeep create mode 100644 crates/chronogrid_net/src/.gitkeep create mode 100644 docs/API_CONTRACTS/ffi_bridge_spec.json create mode 100644 docs/API_CONTRACTS/schema.sql create mode 100644 docs/ARCHITECTURE/01-OSAD-system-architecture.md create mode 100644 docs/ARCHITECTURE/02-security-and-crypto.md create mode 100644 docs/ARCHITECTURE/03-crdt-sync-protocol.md create mode 100644 docs/UI_UX/01-eisenhower-matrix.md create mode 100644 docs/UI_UX/02-calendar-timeblocking.md create mode 100644 docs/UI_UX/03-kanban-gantt-views.md create mode 100644 docs/WORKFLOWS/01-master-user-story.md create mode 100644 docs/WORKFLOWS/02-ingestion-pipeline.md create mode 100644 init_repo.sh create mode 100644 scripts/.gitkeep diff --git a/.clinerules b/.clinerules new file mode 100644 index 0000000..cbd2d7a --- /dev/null +++ b/.clinerules @@ -0,0 +1,14 @@ +# CHRONOGRID P2P - AI CONTEXT & ARCHITECTURAL MANDATES + +1. DATA SOVEREIGNTY & LOCAL-FIRST MANDATE: + - Never generate code that transmits data to third-party cloud endpoints or SaaS providers. + - All network synchronization MUST utilize `crates/chronogrid_net` over libp2p / QUIC with Noise XK encryption. + +2. TECH STACK BOUNDARIES: + - Presentation: Flutter (Win32 for Windows, GTK3 for Linux, Android NDK). + - Core Logic & Storage: Rust (`crates/chronogrid_core`) with SQLCipher & Automerge CRDT. + - FFI Bridge: Use `flutter_rust_bridge` C-ABI generation ONLY. + +3. SINGLE SOURCE OF TRUTH: + - Prior to modifying data structures, consult `docs/API_CONTRACTS/schema.sql` and `docs/ARCHITECTURE/01-OSAD-system-architecture.md`. + - Update documentation in `/docs` concurrently with code changes. diff --git a/.cursor/rules/00-system-mandates.md b/.cursor/rules/00-system-mandates.md new file mode 100644 index 0000000..cbd2d7a --- /dev/null +++ b/.cursor/rules/00-system-mandates.md @@ -0,0 +1,14 @@ +# CHRONOGRID P2P - AI CONTEXT & ARCHITECTURAL MANDATES + +1. DATA SOVEREIGNTY & LOCAL-FIRST MANDATE: + - Never generate code that transmits data to third-party cloud endpoints or SaaS providers. + - All network synchronization MUST utilize `crates/chronogrid_net` over libp2p / QUIC with Noise XK encryption. + +2. TECH STACK BOUNDARIES: + - Presentation: Flutter (Win32 for Windows, GTK3 for Linux, Android NDK). + - Core Logic & Storage: Rust (`crates/chronogrid_core`) with SQLCipher & Automerge CRDT. + - FFI Bridge: Use `flutter_rust_bridge` C-ABI generation ONLY. + +3. SINGLE SOURCE OF TRUTH: + - Prior to modifying data structures, consult `docs/API_CONTRACTS/schema.sql` and `docs/ARCHITECTURE/01-OSAD-system-architecture.md`. + - Update documentation in `/docs` concurrently with code changes. diff --git a/DECISION_LOG.md b/DECISION_LOG.md new file mode 100644 index 0000000..2abe5fd --- /dev/null +++ b/DECISION_LOG.md @@ -0,0 +1,6 @@ +# Architectural Decision Log (ADL) + +## [2026-08-09] - ADL-001: Distributed Local-First System Baseline +- **Status**: Accepted +- **Context**: Design a multi-platform (Windows, Linux, Android, Headless) productivity engine for time, project, and note management without centralized servers. +- **Decision**: Adopted Rust core with SQLCipher local storage, Automerge CRDT delta sync over libp2p, and Flutter presentation layer bound via C-FFI. diff --git a/apps/.gitkeep b/apps/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/apps/chronogrid_daemon/.gitkeep b/apps/chronogrid_daemon/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/apps/chronogrid_daemon/src/.gitkeep b/apps/chronogrid_daemon/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/apps/chronogrid_flutter/.gitkeep b/apps/chronogrid_flutter/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/apps/chronogrid_flutter/lib/.gitkeep b/apps/chronogrid_flutter/lib/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/apps/chronogrid_flutter/lib/src/.gitkeep b/apps/chronogrid_flutter/lib/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/.gitkeep b/crates/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_ai/.gitkeep b/crates/chronogrid_ai/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_ai/src/.gitkeep b/crates/chronogrid_ai/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_core/.gitkeep b/crates/chronogrid_core/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_core/src/.gitkeep b/crates/chronogrid_core/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_crypto/.gitkeep b/crates/chronogrid_crypto/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_crypto/src/.gitkeep b/crates/chronogrid_crypto/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_net/.gitkeep b/crates/chronogrid_net/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/crates/chronogrid_net/src/.gitkeep b/crates/chronogrid_net/src/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/API_CONTRACTS/ffi_bridge_spec.json b/docs/API_CONTRACTS/ffi_bridge_spec.json new file mode 100644 index 0000000..adfffe5 --- /dev/null +++ b/docs/API_CONTRACTS/ffi_bridge_spec.json @@ -0,0 +1,5 @@ +{ + "version": "1.0.0", + "bridge_type": "flutter_rust_bridge", + "targets": ["windows", "linux", "android"] +} diff --git a/docs/API_CONTRACTS/schema.sql b/docs/API_CONTRACTS/schema.sql new file mode 100644 index 0000000..5ca23a7 --- /dev/null +++ b/docs/API_CONTRACTS/schema.sql @@ -0,0 +1,20 @@ +-- Canonical SQLite / SQLCipher Schema Definition +CREATE TABLE IF NOT EXISTS namespaces ( + id TEXT PRIMARY KEY, + name TEXT NOT NULL, + created_at INTEGER NOT NULL +); + +CREATE TABLE IF NOT EXISTS tasks ( + id TEXT PRIMARY KEY, + namespace_id TEXT NOT NULL, + title TEXT NOT NULL, + description_markdown TEXT, + priority_score REAL DEFAULT 0.0, + eisenhower_quadrant INTEGER, + due_date INTEGER, + estimated_duration INTEGER, + status TEXT DEFAULT 'backlog', + hlc_timestamp TEXT NOT NULL, + FOREIGN KEY(namespace_id) REFERENCES namespaces(id) +); diff --git a/docs/ARCHITECTURE/01-OSAD-system-architecture.md b/docs/ARCHITECTURE/01-OSAD-system-architecture.md new file mode 100644 index 0000000..51cdd7c --- /dev/null +++ b/docs/ARCHITECTURE/01-OSAD-system-architecture.md @@ -0,0 +1,4 @@ +# Operational and System Architecture Document (OSAD) +*Status: Active Specification* + +Refer to system blueprints for Flutter presentation layer, Rust Core engine (`chronogrid-core`), and P2P Mesh Network (`chronogrid-net`). diff --git a/docs/ARCHITECTURE/02-security-and-crypto.md b/docs/ARCHITECTURE/02-security-and-crypto.md new file mode 100644 index 0000000..eeddff7 --- /dev/null +++ b/docs/ARCHITECTURE/02-security-and-crypto.md @@ -0,0 +1,9 @@ +# Security & Cryptography Specification + +- **Master Key Derivation**: Argon2id (Memory: 64MB, Iterations: 3, Parallelism: 4). +- **Platform KeyStore Integration**: + - Windows: DPAPI / Credential Manager + - Linux: Freedesktop SecretService API + - Android: Hardware-backed Android KeyStore / TEE +- **Database Cipher**: SQLCipher 4.x (AES-256-CBC with HMAC-SHA512). +- **Transport Security**: Noise XK protocol handshake over QUIC/UDP. diff --git a/docs/ARCHITECTURE/03-crdt-sync-protocol.md b/docs/ARCHITECTURE/03-crdt-sync-protocol.md new file mode 100644 index 0000000..17ab36b --- /dev/null +++ b/docs/ARCHITECTURE/03-crdt-sync-protocol.md @@ -0,0 +1,5 @@ +# CRDT Synchronization Protocol Specification + +- **Engine**: Automerge (Rust) +- **Clock**: Hybrid Logical Clocks (HLC) +- **Resolution Strategy**: Last-Write-Wins Element-Set (LWW-Element-Set) registers for task fields; Tree-CRDT with fractional indexing for project hierarchies. diff --git a/docs/UI_UX/01-eisenhower-matrix.md b/docs/UI_UX/01-eisenhower-matrix.md new file mode 100644 index 0000000..393d697 --- /dev/null +++ b/docs/UI_UX/01-eisenhower-matrix.md @@ -0,0 +1,4 @@ +# Eisenhower Priority Matrix View Specification + +- Dynamic four-quadrant rendering based on Priority Vector Score (S): + S = (Wi * P_user) + (Wu * f(Due_Date - t_current)) + (Wa * Age) diff --git a/docs/UI_UX/02-calendar-timeblocking.md b/docs/UI_UX/02-calendar-timeblocking.md new file mode 100644 index 0000000..caef151 --- /dev/null +++ b/docs/UI_UX/02-calendar-timeblocking.md @@ -0,0 +1,4 @@ +# Calendar & Time-Blocking Grid Specification + +- Bidirectional time-blocking view. +- Local CalDAV endpoint listening on `127.0.0.1`. diff --git a/docs/UI_UX/03-kanban-gantt-views.md b/docs/UI_UX/03-kanban-gantt-views.md new file mode 100644 index 0000000..b110669 --- /dev/null +++ b/docs/UI_UX/03-kanban-gantt-views.md @@ -0,0 +1,4 @@ +# Kanban & Gantt Multi-Project View Specification + +- Multi-level namespace and hierarchy rendering. +- Real-time status column updates mapping to task CRDT state. diff --git a/docs/WORKFLOWS/01-master-user-story.md b/docs/WORKFLOWS/01-master-user-story.md new file mode 100644 index 0000000..8270cce --- /dev/null +++ b/docs/WORKFLOWS/01-master-user-story.md @@ -0,0 +1,6 @@ +# Master User Story: Distributed, Local-First Productivity Engine + +Refer to Master User Story specification for detailed acceptance criteria regarding: +1. Multi-domain IMAP ingestion and local file watchers. +2. Serverless P2P CRDT sync across Windows, Linux, Android, and Headless nodes. +3. Multi-view display execution (Eisenhower Matrix, Time-Blocking Calendar, Kanban, Notes). diff --git a/docs/WORKFLOWS/02-ingestion-pipeline.md b/docs/WORKFLOWS/02-ingestion-pipeline.md new file mode 100644 index 0000000..af73546 --- /dev/null +++ b/docs/WORKFLOWS/02-ingestion-pipeline.md @@ -0,0 +1,5 @@ +# Ingestion & Local Automation Pipeline + +- **Local IMAP Engine**: TLS polling daemon executing inside `chronogrid_core`. +- **System Hotkeys / Widgets**: Native trigger integration for quick jots. +- **AI Processing**: Embedded ONNX / Ollama inference for context routing, task scoring, and duration parsing. diff --git a/init_repo.sh b/init_repo.sh new file mode 100644 index 0000000..ac793e2 --- /dev/null +++ b/init_repo.sh @@ -0,0 +1,166 @@ +#!/usr/bin/env bash +# ============================================================================== +# ChronoGrid P2P Repository & Documentation Structure Initializer +# Target Source Control: git.kellsupport.com +# ============================================================================== + +set -e + +echo "Initializing ChronoGrid P2P repository structure..." + +# 1. Create Workspace Directory Tree +mkdir -p .cursor/rules +mkdir -p docs/ARCHITECTURE +mkdir -p docs/WORKFLOWS +mkdir -p docs/UI_UX +mkdir -p docs/API_CONTRACTS +mkdir -p apps/chronogrid_flutter/lib/src +mkdir -p apps/chronogrid_daemon/src +mkdir -p crates/chronogrid_core/src +mkdir -p crates/chronogrid_net/src +mkdir -p crates/chronogrid_crypto/src +mkdir -p crates/chronogrid_ai/src +mkdir -p scripts + +# 2. Create AI Rules File (.clinerules) +cat << 'EOF' > .clinerules +# CHRONOGRID P2P - AI CONTEXT & ARCHITECTURAL MANDATES + +1. DATA SOVEREIGNTY & LOCAL-FIRST MANDATE: + - Never generate code that transmits data to third-party cloud endpoints or SaaS providers. + - All network synchronization MUST utilize `crates/chronogrid_net` over libp2p / QUIC with Noise XK encryption. + +2. TECH STACK BOUNDARIES: + - Presentation: Flutter (Win32 for Windows, GTK3 for Linux, Android NDK). + - Core Logic & Storage: Rust (`crates/chronogrid_core`) with SQLCipher & Automerge CRDT. + - FFI Bridge: Use `flutter_rust_bridge` C-ABI generation ONLY. + +3. SINGLE SOURCE OF TRUTH: + - Prior to modifying data structures, consult `docs/API_CONTRACTS/schema.sql` and `docs/ARCHITECTURE/01-OSAD-system-architecture.md`. + - Update documentation in `/docs` concurrently with code changes. +EOF + +# Copy .clinerules to .cursor/rules for Cursor IDE compatibility +cp .clinerules .cursor/rules/00-system-mandates.md + +# 3. Create Root Architectural Decision Log +cat << 'EOF' > DECISION_LOG.md +# Architectural Decision Log (ADL) + +## [2026-08-09] - ADL-001: Distributed Local-First System Baseline +- **Status**: Accepted +- **Context**: Design a multi-platform (Windows, Linux, Android, Headless) productivity engine for time, project, and note management without centralized servers. +- **Decision**: Adopted Rust core with SQLCipher local storage, Automerge CRDT delta sync over libp2p, and Flutter presentation layer bound via C-FFI. +EOF + +# 4. Initialize Architecture Documents +cat << 'EOF' > docs/ARCHITECTURE/01-OSAD-system-architecture.md +# Operational and System Architecture Document (OSAD) +*Status: Active Specification* + +Refer to system blueprints for Flutter presentation layer, Rust Core engine (`chronogrid-core`), and P2P Mesh Network (`chronogrid-net`). +EOF + +cat << 'EOF' > docs/ARCHITECTURE/02-security-and-crypto.md +# Security & Cryptography Specification + +- **Master Key Derivation**: Argon2id (Memory: 64MB, Iterations: 3, Parallelism: 4). +- **Platform KeyStore Integration**: + - Windows: DPAPI / Credential Manager + - Linux: Freedesktop SecretService API + - Android: Hardware-backed Android KeyStore / TEE +- **Database Cipher**: SQLCipher 4.x (AES-256-CBC with HMAC-SHA512). +- **Transport Security**: Noise XK protocol handshake over QUIC/UDP. +EOF + +cat << 'EOF' > docs/ARCHITECTURE/03-crdt-sync-protocol.md +# CRDT Synchronization Protocol Specification + +- **Engine**: Automerge (Rust) +- **Clock**: Hybrid Logical Clocks (HLC) +- **Resolution Strategy**: Last-Write-Wins Element-Set (LWW-Element-Set) registers for task fields; Tree-CRDT with fractional indexing for project hierarchies. +EOF + +# 5. Initialize Workflow Documents +cat << 'EOF' > docs/WORKFLOWS/01-master-user-story.md +# Master User Story: Distributed, Local-First Productivity Engine + +Refer to Master User Story specification for detailed acceptance criteria regarding: +1. Multi-domain IMAP ingestion and local file watchers. +2. Serverless P2P CRDT sync across Windows, Linux, Android, and Headless nodes. +3. Multi-view display execution (Eisenhower Matrix, Time-Blocking Calendar, Kanban, Notes). +EOF + +cat << 'EOF' > docs/WORKFLOWS/02-ingestion-pipeline.md +# Ingestion & Local Automation Pipeline + +- **Local IMAP Engine**: TLS polling daemon executing inside `chronogrid_core`. +- **System Hotkeys / Widgets**: Native trigger integration for quick jots. +- **AI Processing**: Embedded ONNX / Ollama inference for context routing, task scoring, and duration parsing. +EOF + +# 6. Initialize UI/UX Documents +cat << 'EOF' > docs/UI_UX/01-eisenhower-matrix.md +# Eisenhower Priority Matrix View Specification + +- Dynamic four-quadrant rendering based on Priority Vector Score (S): + S = (Wi * P_user) + (Wu * f(Due_Date - t_current)) + (Wa * Age) +EOF + +cat << 'EOF' > docs/UI_UX/02-calendar-timeblocking.md +# Calendar & Time-Blocking Grid Specification + +- Bidirectional time-blocking view. +- Local CalDAV endpoint listening on `127.0.0.1`. +EOF + +cat << 'EOF' > docs/UI_UX/03-kanban-gantt-views.md +# Kanban & Gantt Multi-Project View Specification + +- Multi-level namespace and hierarchy rendering. +- Real-time status column updates mapping to task CRDT state. +EOF + +# 7. Initialize API Contracts & Schema +cat << 'EOF' > docs/API_CONTRACTS/schema.sql +-- Canonical SQLite / SQLCipher Schema Definition +CREATE TABLE IF NOT EXISTS namespaces ( + id TEXT PRIMARY KEY, + name TEXT NOT NULL, + created_at INTEGER NOT NULL +); + +CREATE TABLE IF NOT EXISTS tasks ( + id TEXT PRIMARY KEY, + namespace_id TEXT NOT NULL, + title TEXT NOT NULL, + description_markdown TEXT, + priority_score REAL DEFAULT 0.0, + eisenhower_quadrant INTEGER, + due_date INTEGER, + estimated_duration INTEGER, + status TEXT DEFAULT 'backlog', + hlc_timestamp TEXT NOT NULL, + FOREIGN KEY(namespace_id) REFERENCES namespaces(id) +); +EOF + +cat << 'EOF' > docs/API_CONTRACTS/ffi_bridge_spec.json +{ + "version": "1.0.0", + "bridge_type": "flutter_rust_bridge", + "targets": ["windows", "linux", "android"] +} +EOF + +# 8. Add .gitkeep to code folders to ensure empty directories are committed to Git +find apps crates scripts -type d -exec touch {}/.gitkeep \; + +echo "Directory structure successfully created and populated!" +echo "" +echo "Next steps to push to git.kellsupport.com:" +echo " git init" +echo " git remote add origin https://git.kellsupport.com/kell-engineering/chronogrid.git" +echo " git add ." +echo " git commit -m 'Initial commit: Complete OSAD architecture, specs, and repository structure'" +echo " git push -u origin main" \ No newline at end of file diff --git a/scripts/.gitkeep b/scripts/.gitkeep new file mode 100644 index 0000000..e69de29