Knowledge Platform

A modular, graph-first, local-first knowledge-work application built with Python and PySide6.

What Is It?

The Knowledge Platform stores and versions structured graphs as its primary user-facing artifact. Each graph is governed by a graph type that defines the semantics of its nodes and edges. Modules (plugins) extend the platform with new graph types, domain services, projections, and UI widgets, and the host loads them from runtime configuration instead of hard-coded imports.

Think of it as a programmable knowledge graph where you define exactly what kinds of entities and relationships matter for your domain.

Architecture Overview

graph TB
    subgraph UI
        MW[MainWindow]
        OV[OutlineView]
        EB[AppEventBus]
        MW --- OV
        MW --- EB
    end

    subgraph SVC
        GS[GraphService]
        WS[WorkspaceService]
        IF[Service Protocols]
    end

    subgraph DOMAIN
        TR[TypeRegistry]
        GT[GraphType Schemas]
        TR --- GT
    end

    subgraph CORE
        ENG[GraphEngine]
        G[Graph Aggregate]
        TX[Transaction]
        ENG --- G
        ENG --- TX
    end

    subgraph MOD
        OM[OutlineModule]
        OS[OutlineService]
        OM --- OS
    end

    subgraph PERSIST
        REPO[SqliteGraphRepository]
        DB[(SQLite)]
        REPO --- DB
    end

    UI -->|service calls| SVC
    SVC --> DOMAIN
    SVC --> CORE
    CORE --> PERSIST
    MOD --> SVC
    MOD --> DOMAIN

Quick Start

Prerequisites

  • Python 3.11+
  • pip or hatch

Install

# Clone and enter the repo
git clone <repo-url> knowledge-platform
cd knowledge-platform

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

# Install with all dev dependencies
pip install -e ".[dev]"

Run the Application

knowledge-platform

Modules are loaded from modules.yaml. The loader checks:

  1. KNOWLEDGE_PLATFORM_MODULES_FILE
  2. ~/.knowledge_platform/modules.yaml
  3. the packaged default config

Run the Tests

# All tests with coverage report
pytest

# Unit tests only (no coverage, faster)
pytest tests/unit --no-cov

Documentation Map

Section What You'll Find
Working with Graphs Core concepts, workspaces, nodes, edges, the service API
Outline Module Creating outlines, adding items, the tree projection, UI walkthrough
Use Cases Real-world scenarios: book outlines, meeting notes, WBS, knowledge bases
Module Development Full guide to building a new plugin from scratch
API Reference Complete API docs for every layer
DESIGN.md (repo root) Architecture decisions, patterns, Mermaid diagrams — view on GitHub
Updating the Docs How to serve, build, and extend this documentation

Current Modules

Module ID Description
Outline outline Hierarchical document outline backed by a tree graph

Project Status

Alpha — The core engine, service layer, persistence, and Outline module are complete and tested. Workspaces persist to SQLite, and module loading is now configuration-driven. The next architectural milestone is validating the host with a second independently loaded module.

See DESIGN.md in the repository root for the full roadmap and architectural details.