Kyle Isom
83f4b327f3
ARCHITECTURE.md covers the system design: exod backend, single Kotlin desktop app (Obsidian-style), layered architecture, data flow, CAS blob store, cross-pillar integration, and key design decisions. PROJECT_PLAN.md defines six implementation phases from foundation through remote access, with concrete deliverables per phase. CLAUDE.md updated to reference both documents and reflect the single-app UI decision with unified search. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
46 lines
2.6 KiB
Markdown
46 lines
2.6 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**kExocortex** is a personal knowledge management system — an "exocortex" for capturing, organizing, and retrieving knowledge. It combines two pillars: an **artifact repository** (for storing source documents like PDFs, papers, webpages) and a **knowledge graph** (for linking notes and ideas).
|
|
|
|
The project is in active design and early implementation. See `ARCHITECTURE.md` for the technical system design and `PROJECT_PLAN.md` for the phased implementation plan.
|
|
|
|
## Repository Structure
|
|
|
|
- `docs/` — Design documentation and specifications (the active part of the repo)
|
|
- `docs/KExocortex/Spec.md` — Functional specification (use cases, system design, milestones)
|
|
- `docs/KExocortex/Elements.md` — Core conceptual elements (artifacts, notes, structure, interfaces, locality, totality)
|
|
- `docs/KExocortex/History.md` — Design evolution and prior art analysis
|
|
- `docs/KExocortex/Datastore.md` — Storage architecture decisions (SQLite + content-addressable blob store)
|
|
- `ark/` — **Archived code.** Contains previous implementation attempts (Go v1, Go v2, Java). View for historical context only; do not modify.
|
|
- `*.db` — SQLite databases (`artifacts.db`, `exo.db`)
|
|
|
|
## Key Concepts
|
|
|
|
- **Artifact**: A source document (PDF, webpage, book) stored with metadata, tags, categories, citation info, and versioned snapshots. Stored in a content-addressable blob store with metadata in SQLite.
|
|
- **Knowledge Graph**: A graph of notes linking ideas and artifacts. Notes are distillations of knowledge from artifacts. Structure is hierarchical with cross-links.
|
|
- **Nodes**: Graph entries that are either notes or artifact links. Named by path (e.g. `root=>note2=>note3`).
|
|
- **Backend**: Planned as `exod` gRPC server with SQLite storage, local blob store, and optional remote Minio backup.
|
|
|
|
## Tech Stack
|
|
|
|
- **Go** — Infrastructure, backend server, and CLI tools
|
|
- **Kotlin** — Desktop applications for all user interfaces (no web frontends)
|
|
|
|
## Architecture (from Spec)
|
|
|
|
The system design calls for:
|
|
1. A backend server (`exod`) with gRPC endpoints (Go)
|
|
2. SQLite database (single unified DB preferred over split)
|
|
3. Local blob store (content-addressable)
|
|
4. Remote Minio backup for blobs
|
|
5. Reverse-proxy frontend over Tailscale for remote/mobile access
|
|
6. Single Kotlin desktop app (Obsidian-style layout) with tree sidebar, contextual main panel, graph view, and unified search with selector prefixes
|
|
|
|
## Git Remote
|
|
|
|
`git@git.wntrmute.dev:kyle/exo.git` — branch `master`
|