Architecture & Technical Specifications

Taxon is structured as a modular suite sharing a unified Rust core library and local persistence engine.

┌─────────────────────────────────────────────────────────────────────────┐
│                                TAXON SUITE                              │
├──────────────────────────┬──────────────────────────────────────────────┤
│  Frontend Desktop (GUI)  │  Terminal Ecosystem (CLI & TUI)             │
│  React 18 + Vite + Tauri │  taxon-cli (Ratatui 0.29 + Crossterm)        │
└────────────┬─────────────┴──────────────────────┬───────────────────────┘
             │                                    │
             ▼                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                              taxon-core                                 │
│  • SQLite Database Engine (rusqlite)                                    │
│  • YAML / Frontmatter Parser & Markdown Serializer                      │
│  • Two-way Diffing & Sync Engine                                        │
│  • Vault Directory Scanner & Model Definitions                          │
└─────────────────────────────────────────────────────────────────────────┘

---

SQLite Database Schema (taxon.db)

Taxon stores primary application state in SQLite at ~/.config/com.taxon.app/taxon.db:

projects

• id (TEXT PRIMARY KEY): Unique project ID (e.g. proj_1783077504863).
• name (TEXT NOT NULL): Human-readable project name.
• category (TEXT): Categorization grouping.
• vaultPath (TEXT): Path to .taxon/ local vault.
• workspacePaths (TEXT JSON): Array of code workspace roots.
• pinned (INTEGER 0/1): Pin state for Alt 1..9 quick switching.

tasks

• id (TEXT PRIMARY KEY): Alphanumeric task ID (e.g. doc001 or a1b2c3).
• projectId (TEXT): Foreign key to projects.id.
• sprintId (TEXT): Foreign key to sprints.id (NULL for backlog).
• title (TEXT NOT NULL): Task title.
• priority (TEXT): Critical, High, Medium, or Low.
• status (TEXT): To Do, In Progress, Need to Test, or Done.
• moduleGroup (TEXT): Coarse architectural group for DAG layout.
• dependsOn (TEXT JSON): Array of prerequisite task IDs.
• subtasks (TEXT JSON): Array of { id, title, completed }.

sprints

• id (TEXT PRIMARY KEY): Sprint identifier (e.g. doc014 or sp1234).
• name (TEXT NOT NULL): Sprint display title.
• status (TEXT): Planned, Active, or Completed.
• startDate / endDate (TEXT): Date ranges (YYYY-MM-DD).
• goal (TEXT): Markdown sprint objective.

---

.taxon/ File Contract Specification

Task Contract (.taxon/tasks/TASK-{id}-{slug}.md)

---
id: a1b2c3
title: Implement Authentication Flow
priority: High
status: To Do
completed: false
sprintId: sp1234
moduleGroup: Authentication
dependsOn:
  - x9y8z7
inputs:
  - docs/contracts/auth-ipc.md
outputs:
  - src/components/LoginScreen.tsx
  - src/hooks/useAuth.ts
linkedFiles:
  - src/components/LoginScreen.tsx
labels:
  - frontend
  - auth
---
## Description
Task specification and context.

## Deliverables
- [Component](file:///path/to/file): Description.

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Subtasks
- [ ] Subtask 1

---

Tauri IPC Commands Reference

IPC Command	Arguments	Return Type	Description
get_task_diff_summary	projectPath, workspacePath, baseCommit	FileDiffSummary[]	Computes file delta between workspace and baseline commit.
launch_sandbox_terminal	worktreePath	void	Spawns user’s native terminal emulator inside worktree directory.
launch_sandbox_editor	worktreePath, editorCmd	void	Spawns code editor ($EDITOR or VS Code) inside worktree directory.
export_to_taxon_files	projectId, vaultPath	SyncResult	Serializes SQLite state into .taxon/ markdown files.
import_from_taxon_files	projectId, vaultPath	SyncDiff	Ingests disk changes from .taxon/ into SQLite database.