This is a monorepo aimed at developers building nostr applications in rust. All crates are prefixed by the namespace `coracle`.

It has the following crates:

- `coracle-lib` - Struct definitions, stateless utilities related to nostr.
- `coracle-net` - Networking utilities for working with relays
- `coracle-signer` - Signer client/server utilities
- `coracle-domain` - Domain-specific nostr types: profiles, follows, reactions, zaps, etc.
- `coracle-content` - Text parsing and rendering utilities
- `coracle-storage` - Storage adapters for different platforms

All code is written in a [literate programming](https://en.wikipedia.org/wiki/Literate_programming) style and compiled to both html documentation and rust source code. The goal of this repository is threefold:

- To create a complete resource for learning how to work with the nostr protocol for humans
- To create a production-ready nostr utility library for inclusion in rust, KMP, and web projects.
- To experiment with using literate programming to serve both as a library and context file for LLMs.

## Prerequisites

- [Rust](https://rustup.rs/)
- [just](https://github.com/casey/just)
- [mdbook](https://rust-lang.github.io/mdBook/) (`cargo install mdbook`)

## How it works

The source of truth is the `book/` directory, which contains markdown files written in a literate programming style. Code blocks annotated with a file path are extracted ("tangled") into Rust source files by the `coracle-tangle` tool.

For example, a code block like this in a markdown file:

```text
  ```rust {file=coracle-lib/src/event.rs}
  pub struct Event { ... }
  ```
```

will be extracted to `coracle-lib/src/event.rs`. Multiple blocks targeting the same file are concatenated in document order, so you can introduce a struct in one section and add methods to it later in the narrative.

Code blocks without a `{file=...}` annotation are illustrative only and are not tangled.

The `src/` directories of the library crates are generated artifacts and should not be edited directly. Edit the markdown in `book/` instead.

## Usage

```sh
# Tangle: extract code from markdown into .rs files
just tangle

# Build: tangle + compile all library crates
just build

# Check: tangle + type-check without full compilation
just check

# Weave: tangle + generate the HTML book (output in target/book/)
just weave

# Clean: remove all generated source and book output
just clean

# All: build + weave
just all
```

## Project structure

```
book/               # Literate source (the single source of truth)
  book.toml         # mdBook configuration
  SUMMARY.md        # Table of contents
  01-introduction.md
  02-events.md      # etc.
coracle-tangle/     # The tangle/weave tool (Rust binary)
coracle-lib/        # Core nostr types and utilities (generated src/)
coracle-net/        # Relay networking (generated src/)
coracle-signer/     # Signing abstractions (generated src/)
coracle-content/    # Content parsing (generated src/)
coracle-storage/    # Storage adapters (generated src/)
```