# 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.