Skip to content

athens-research-tutorial

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

athens-research-tutorial

README.md

layout default
title Athens Research Knowledge Graph
nav_order 39
has_children true
format_version v2

Athens Research: Deep Dive Tutorial

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

Stars License: EPL 1.0 ClojureScript

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

What Is Athens Research?

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
Loading

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

Tech Stack

Component Technology
Language ClojureScript
UI Framework Reagent (React wrapper)
State Re-frame
Database Datascript (in-memory graph)
Desktop Electron

Ready to begin? Start with Chapter 1: System Overview.

Built with insights from the Athens Research repository and community documentation.

Related Tutorials

Navigation & Backlinks

Full Chapter Map

  1. Chapter 1: System Overview
  2. Chapter 2: Datascript Deep Dive
  3. Chapter 3: Schema Design
  4. Chapter 4: Application Architecture
  5. Chapter 5: Component System
  6. Chapter 6: Event Handling
  7. Chapter 7: Block Editor
  8. Chapter 8: Rich Text

Current Snapshot (auto-updated)

What You Will Learn

  • how Athens uses Datascript as an in-memory graph database for knowledge storage
  • how bi-directional links and backlinks are managed across pages and blocks
  • how Re-frame events and subscriptions drive the ClojureScript application state
  • how the block editor handles recursive rendering and outliner-style editing

Source References

Generated by AI Codebase Knowledge Builder