Athens Research: Deep Dive Tutorial

June 22, 2026 · View on GitHub

Project Status: The Athens Research repository was archived in August 2022 and is no longer actively maintained. This tutorial covers the final v2.0.0 release as a historical reference for ClojureScript/Datascript architectural patterns. Do not use Athens as the basis for new production projects.

Project: Athens Research — An open-source, Roam-like knowledge management system built with ClojureScript and graph databases.

Why This Track Matters

Athens Research demonstrates how a graph-first, local-first knowledge system can be built with ClojureScript and Datascript, offering a fully self-hosted alternative to cloud knowledge tools.

This track focuses on:

understanding block-based editing with bi-directional link management
working with Datascript in-memory graph databases for knowledge relationships
building ClojureScript frontends with Re-frame state management
operating a local-first system with optional real-time collaboration

Athens is an open-source knowledge management system inspired by Roam Research. It uses Datascript (an in-memory graph database) with ClojureScript to provide block-based editing, bi-directional linking, and knowledge graph visualization — all running locally for full data ownership.

Feature	Description
Block-Based Editor	Flexible, composable content editing with outliner UX
Bi-Directional Links	Automatic backlinks between pages and blocks
Graph Database	Datascript in-memory graph for knowledge relationships
Knowledge Graph	Interactive visualization of connections between notes
Local-First	All data stored locally, no cloud dependency
Real-Time Collab	Multi-user editing with conflict resolution

Mental Model

graph TB
    subgraph Frontend["ClojureScript Frontend"]
        EDITOR[Block Editor]
        GRAPH[Graph Visualization]
        SEARCH[Search Interface]
    end

    subgraph State["State Management"]
        REFRAME[Re-frame Events]
        SUBS[Subscriptions]
    end

    subgraph Data["Data Layer"]
        DS[(Datascript DB)]
        FS[File System]
        SYNC[Sync Engine]
    end

    Frontend --> State
    State --> Data

Chapter Guide

Chapter	Topic	What You'll Learn
1. System Overview	Architecture	Athens's approach to knowledge management
2. Datascript Database	Data Layer	In-memory graph database, queries, transactions
3. Schema Design	Data Model	Blocks, pages, and relationship modeling
4. Application Architecture	App Flow	Re-frame event flow and state boundaries
5. Component System	UI Layer	Reagent composition and recursive block rendering
6. Event Handling	State Changes	Editing, navigation, and sync event orchestration
7. Block Editor	Editor Core	Outliner commands, hierarchy edits, and UX behavior
8. Rich Text	Rendering	Rich-text tokenization, AST rendering, and safeguards