# DocumentForge

> An embedded JSON document database for .NET: SQL-like queries over JSON documents, persistent B-tree indexes, write-ahead-log durability, logical replication, and consistent-hash sharding. Runs as a single dependency-free binary or a NuGet package, and scales from one file to a sharded cluster.

The developer portal lives at https://documentforge.aerotoys.io/docs. Pages are also available as MDX in the `aerotoysio/documentforge-docs` repository under `portal/content/`.

## Start here
- [Introduction](https://documentforge.aerotoys.io/docs/): What DocumentForge is and how to navigate the docs.
- [Quickstart](https://documentforge.aerotoys.io/docs/quickstart/): First query in five minutes — embedded (.NET) and server (dfdb).
- [Using with AI agents](https://documentforge.aerotoys.io/docs/ai-agents/): Compact copy-paste reference for AI coding agents.

## Concepts
- [Documents](https://documentforge.aerotoys.io/docs/concepts/documents/): JSON values stored as BSON, addressed for fast lookup.
- [Collections](https://documentforge.aerotoys.io/docs/concepts/collections/): Schema-free groups of documents.
- [Data modeling](https://documentforge.aerotoys.io/docs/concepts/data-modeling/): Embed vs reference; indexing strategy.
- [Indexes](https://documentforge.aerotoys.io/docs/concepts/indexes/): Persistent B-tree indexes over document paths.
- [Transactions](https://documentforge.aerotoys.io/docs/concepts/transactions/): Atomic writes, WAL durability, crash recovery, cross-shard 2PC.
- [Replication](https://documentforge.aerotoys.io/docs/concepts/replication/): Logical replication, catchup, auto-failover.
- [Sharding](https://documentforge.aerotoys.io/docs/concepts/sharding/): Stateless router, consistent-hash routing, online rebalance.

## Reference
- [SQL](https://documentforge.aerotoys.io/docs/reference/sql/): Supported clauses, operators, and functions with examples.
- [.NET SDK](https://documentforge.aerotoys.io/docs/reference/sdk-net/): DocumentForgeDb, the typed LINQ surface, and the REPL.
- [REST API](https://documentforge.aerotoys.io/docs/reference/rest/): HTTP endpoints exposed by dfdb serve.
- [CLI](https://documentforge.aerotoys.io/docs/reference/cli/): Every dfdb subcommand and flag.
- [Configuration](https://documentforge.aerotoys.io/docs/reference/config/): node.json fields, environment variables, and CLI flags.

## Guides
- [Indexing strategy](https://documentforge.aerotoys.io/docs/guides/indexing/): What to index and the cost of each index.
- [Setting up replication](https://documentforge.aerotoys.io/docs/guides/replication/): Leader, follower, and failover.
- [Deployment](https://documentforge.aerotoys.io/docs/guides/deployment/): Binary, Docker, and Render.
- [Security](https://documentforge.aerotoys.io/docs/guides/security/): API keys, replication secrets, TLS, threat model.
- [Backup & restore](https://documentforge.aerotoys.io/docs/guides/backup-restore/): Safe copies and engine upgrades.
- [Monitoring](https://documentforge.aerotoys.io/docs/guides/monitoring/): What to watch in production.