exo/PROJECT_PLAN.md

Project Plan

Implementation plan for kExocortex, organized into phases with concrete deliverables.

Current State

What exists:

• Comprehensive design documentation in docs/KExocortex/ covering the artifact data model, knowledge graph design, system architecture, UI considerations, and taxonomy
• Three archived implementations in ark/ (Go v1, Go v2, Java) that validated the artifact repository data model, SQLite schema, and content-addressable blob store
• A proven database schema (11 tables) and Go domain types for the artifact pillar
• Protobuf sketches for the knowledge graph EAV tuple model

What doesn't exist yet:

• Active codebase (all code is archived)
• The exod gRPC server
• Knowledge graph implementation beyond stubs
• Kotlin desktop application
• Minio sync queue
• Protobuf/gRPC service definitions

Phase 1: Foundation

Establish the Go project structure, shared types, and database infrastructure.

Deliverables:

• Go module (go.mod) with project structure
• core package: Header, Metadata, Value types, UUID generation
• SQLite migration framework and initial schema (ported from ark/go-v2/schema/artifacts.sql)
• Database access layer: connection management, transaction helpers (StartTX/EndTX pattern)
• Configuration: paths for database, blob store, Minio endpoint

Key references:

• docs/KExocortex/Spec/Artifacts.md — Header and Metadata type definitions
• ark/go-v2/types/common/common.go — Proven shared type implementations
• ark/go-v2/types/artifacts/db.go — Proven database access patterns
• ark/go-v2/schema/artifacts.sql — Proven schema

Phase 2: Artifact Repository

Build the artifact pillar — the most mature and validated part of the design.

Deliverables:

• artifacts package: Artifact, Snapshot, Blob, Citation, Publisher types with Get/Store methods
• Tag and category management (shared pool, idempotent upserts)
• Content-addressable blob store (SHA256 hashing, hierarchical directory layout, read/write)
• YAML import for bootstrapping from existing artifact files
• Protobuf message definitions for all artifact types
• gRPC service: create/get/update/delete artifacts, store/retrieve blobs, manage tags and categories

Key references:

• docs/KExocortex/Spec/Artifacts.md — Canonical type definitions
• ark/go-v2/types/artifacts/*.go — Proven implementations of all artifact types
• ark/go-v2/cmd/exo-repo/cmd/import.go — Proven import flow

Phase 3: CLI Tools

Build command-line tools that connect to exod via gRPC for scripting and administrative use.

Deliverables:

• exo CLI binary using Cobra (or similar)
• Commands: import (YAML artifacts), tag (add/list/delete), cat (add/list/delete), search (by tag, category, title, DOI)
• exod server binary with startup, shutdown, and configuration

Key references:

• ark/go-v2/cmd/exo-repo/cmd/*.go — Proven command structure (import, tags, cat)

Phase 4: Knowledge Graph

Build the knowledge graph pillar — the less mature component requiring more design work.

Deliverables:

• kg package: Node, Cell, Fact types
• Database schema additions for knowledge graph tables (nodes, cells, facts, graph edges) in the unified SQLite database
• EAV tuple storage with transaction timestamps and retraction support
• Node-to-artifact linking (cross-pillar references)
• Cell content types (markdown, code, etc.)
• gRPC service: create/get/update nodes, add cells, record facts, traverse graph
• CLI commands for node creation and graph queries

Key references:

• docs/KExocortex/KnowledgeGraph/Tuple.md — EAV/Fact protobuf model
• docs/KExocortex/KnowledgeGraph.md — Graph structure design
• docs/KExocortex/Taxonomy.md — Note naming conventions (C2 wiki style)
• docs/KExocortex/Elements.md — Note and structure definitions
• ark/go-v2/types/kg/ — Type stubs (Node, Cell)

Phase 5: Desktop Application

Single Kotlin desktop app for both artifact management and knowledge graph interaction. Obsidian-style layout: tree/outline sidebar, contextual main panel, graph visualization, unified search.

Deliverables (incremental):

1. App shell and sidebar — gRPC client connecting to exod. Tree/outline sidebar showing knowledge graph hierarchy and an unlinked-artifacts section. Basic navigation.
2. Artifact views — Artifact detail panel (citation, snapshot history, blob preview). Import flow (file or URL → citation form → tags/categories). Catalog view for untagged/unlinked artifacts needing attention.
3. Note editor — Cell-based editor (markdown, code blocks). Ctrl+L note creation. Inline display of associated artifacts.
4. Unified search — Single search bar across both pillars. Selector prefixes for precision (artifact:, note:, cell:, tag:, author:, doi:). Fuzzy matching for partial recall.
5. Graph view — Visual node graph (toggle or separate pane, Obsidian-style). Exploration by traversing connections and discovering clusters.
6. Command palette — Ctrl+Shift+A for quick actions: create note, import artifact, search, switch views, manage tags.
7. Presentation/export — Export curated notes with associated artifacts to HTML or PDF.

Key references:

• docs/KExocortex/UI.md — Interaction patterns to adopt (IntelliJ action menu, Dendron Ctrl+L)
• docs/KExocortex/Elements.md — Interface definitions (query, exploration, presentation, update)
• docs/KExocortex/About.md — Litmus test: Camerata article retrieval with readable snapshot
• docs/KExocortex/Taxonomy.md — C2 wiki style node naming for sidebar hierarchy

Phase 6: Remote Access & Backup

Enable remote capture and blob backup.

Deliverables:

• Minio sync queue in exod: async blob replication, retry on failure, restore from remote
• Tailscale reverse proxy configuration with TLS and HTTP basic auth
• Quick-capture endpoint: accept URL or document from mobile, stash in artifact repository for later categorization
• Cataloging view: list artifacts needing tags or node attachment

Key references:

• docs/KExocortex/Spec.md — Remote access architecture, mobile reading use case
• docs/KExocortex/RDD/2022/02/23.md — Original web server goal for URL/PDF stashing
• docs/KExocortex/Agents.md — Future agent integration via Tailscale

Phase Dependencies

Phase 1: Foundation
    │
    ▼
Phase 2: Artifact Repository ──► Phase 3: CLI Tools
    │
    ▼
Phase 4: Knowledge Graph
    │
    ▼
Phase 5: Desktop Application
    │
    ▼
Phase 6: Remote Access & Backup

Phases 2 and 3 can overlap — CLI commands can be built as gRPC endpoints come online. Phase 5 can begin its Update facet once Phase 2 is complete, with remaining facets built as Phase 4 delivers.