From e86ffffe0ec5554794c41c32e34af62ddc84d44d Mon Sep 17 00:00:00 2001
From: Wojtek <wskozlowski@dbzero.io>
Date: Thu, 4 Dec 2025 12:23:05 +0100
Subject: [PATCH 1/5] readme

---
 README.md | 412 ++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 351 insertions(+), 61 deletions(-)

diff --git a/README.md b/README.md
index 469298d7..fa577d10 100644
--- a/README.md
+++ b/README.md
@@ -1,101 +1,391 @@
 # dbzero
 
-dbzero Community Edition
+**A state management system for Python 3.x that unifies your application's business logic, data persistence, and caching into a single, efficient layer.**
 
-## License
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See `LICENSE` for the full text.
+---
 
-- If you modify and run this software over a network, you must offer the complete corresponding source code to users interacting with it (AGPLv3 §13).
-- Redistributions must preserve copyright and license notices and provide source.
+## Overview
 
-For a short summary, see `COPYING`. For attribution details, see `NOTICE`.
+**dbzero** lets you code as if you have infinite memory. Inspired by a thought experiment from *Architecture Patterns with Python* by Harry Percival and Bob Gregory, dbzero handles the complexities of data management in the background while you work with simple Python objects.
+
+The result is a simplified application stack that can eliminate the need for separate databases, ORMs, and caching layers—reducing development time by up to **80%**.
+
+---
 
-## Getting started
+## Key Features
 
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+### Database Capabilities
+- **ACID Transactions** - Serializable consistency guarantees for all data operations
+- **Single-writer, Multiple-reader** concurrency model
+- **Automatic Persistence** - Objects are automatically saved to disk
+- **Efficient Caching** - Only accessed data is loaded into memory
+- **Time Travel** - Query historical states at any transaction point
+- **Horizontal Scalability** - Built-in support for data partitioning and sharding
 
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+### Developer Experience
+- **Invisible by Design** - Minimal API surface; write regular Python code
+- **Dynamic Schema** - No separate data models or schema definitions needed
+- **AI-Friendly** - Works exceptionally well with AI coding agents
+- **Type Support** - Full support for Python's built-in types and collections
+- **Reference Counting** - Automatic garbage collection of unused objects
 
-## Add your files
+---
 
-- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
+## Quick Start
 
+### Installation
+
+```bash
+pip install dbzero
 ```
-cd existing_repo
-git remote add origin https://gitlab-01.itx.pl/wkozlowski/dbzero.git
-git branch -M main
-git push -uf origin main
+
+### Hello World Example
+
+```python
+import dbzero as db0
+
+@db0.memo(singleton=True)
+class Root:
+    def __init__(self, greeting):
+        self.greeting = greeting
+
+    def greet(self):
+        print(self.greeting)
+
+if __name__ == "__main__":
+    if db0.exists(Root):
+        print("Process started with data...")
+        root = db0.fetch(Root)
+    else:
+        root = Root("Hello, World!")
+    
+    root.greet()  # Output: Hello, World!
 ```
 
-## Integrate with your tools
+When the process exits, the application state is persisted automatically. The same data will be available the next time the app starts.
 
-- [ ] [Set up project integrations](https://gitlab-01.itx.pl/wkozlowski/dbzero/-/settings/integrations)
+---
 
-## Collaborate with your team
+## Core Concepts
 
-- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
-- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
-- [ ] [Automatically merge when pipeline succeeds](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
+### Memo Classes
 
-## Test and Deploy
+Transform any Python class into a persistent, managed object by applying the `@db0.memo` decorator:
 
-Use the built-in continuous integration in GitLab.
+```python
+import dbzero as db0
 
-- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
+@db0.memo
+class Person:
+    def __init__(self, name: str, age: int):
+        self.name = name
+        self.age = age
 
-***
+# Instantiation works just like regular Python
+person = Person("Alice", 30)
 
-# Editing this README
+# Attributes can be modified dynamically
+person.age += 1
+person.address = "123 Main St"  # Add new attributes on the fly
+```
 
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!).  Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.
+**Features of memo classes:**
+- Automatic durability and persistence
+- Efficient memory/disk management
+- Automatic UUID assignment
+- Support for tagging and querying
+- Reference counting for garbage collection
 
-## Suggestions for a good README
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+### Collections
 
-## Name
-Choose a self-explaining name for your project.
+dbzero provides durable, transactional versions of Python's built-in collections:
 
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+```python
+# Create persistent collections
+my_dict = db0.dict(name="Alice", age=30)
+my_list = db0.list([1, 2, 3, 4, 5])
+my_tuple = db0.tuple(("a", "b", "c"))
 
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+# They work just like standard Python collections
+my_dict["city"] = "New York"
+my_list.append(6)
+print(len(my_list))  # 6
+```
 
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+All standard operations are supported, and changes are automatically persisted within transactions.
 
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+### Transactions
 
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+By default, dbzero uses **autocommit** mode, periodically persisting changes to storage:
 
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+```python
+# Manual commit for batch operations
+tasks = db0.list()
+for i in range(100):
+    tasks.append(Task(f"Task {i}"))
 
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
+db0.commit()  # Persist all 100 tasks at once
+```
 
-## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
+### Queries and Tags
+
+Find objects using type-based queries and flexible tag logic:
+
+```python
+# Create and tag objects
+person = Person("Alice", 30)
+db0.tags(person).add("employee")
+db0.tags(person).add("manager")
+
+# Find by type
+all_persons = db0.find(Person)
+
+# Find by tag
+managers = db0.find("manager")
+
+# Combine type and tags (AND logic)
+employee_persons = db0.find(Person, "employee")
+
+# OR logic using a list
+results = db0.find(["tag1", "tag2"])
+
+# NOT logic using db0.no()
+non_managers = db0.find("employee", db0.no("manager"))
+```
+
+### Snapshots and Time Travel
+
+Create isolated, read-only views of your data at any point in time:
+
+```python
+# Create a snapshot of the current state
+with db0.snapshot() as snap:
+    # Changes to live objects won't affect the snapshot
+    obj.value = 999
+    
+    # Query the snapshot - sees old data
+    old_obj = snap.fetch(MemoTestClass)
+    assert old_obj.value == 123
+
+# Time travel to a specific transaction
+state_num = db0.get_state_num()
+# ... make changes ...
+
+with db0.snapshot(state_num) as past_snap:
+    # Access data exactly as it was at that state
+    past_obj = past_snap.fetch(obj_uuid)
+```
+
+### Prefixes (Data Partitioning)
+
+Organize data into isolated partitions with independent commit histories:
+
+```python
+# Scope a class to a specific prefix
+@db0.memo(prefix="settings-prefix")
+class AppSettings:
+    def __init__(self, theme: str):
+        self.theme = theme
+
+# Open and work with different prefixes
+db0.open("user-data", "rw")  # Set current prefix
+settings = AppSettings(theme="dark")  # Goes to "settings-prefix"
+note = UserNote(content="Hello")      # Goes to "user-data"
+```
+
+### Indexes
+
+Create fast, sorted access to your data:
+
+```python
+# Create an index
+priority_queue = db0.index()
+
+# Add items with keys for sorting
+task1 = Task("High priority task")
+task2 = Task("Low priority task")
+
+priority_queue.add(1, task1)  # key=1
+priority_queue.add(10, task2)  # key=10
+
+# Iterate in sorted order
+for key, task in priority_queue:
+    print(f"Priority {key}: {task.description}")
+```
+
+---
+
+## Advanced Features
+
+### Multi-Process Synchronization
+
+dbzero automatically synchronizes data between processes:
+
+```python
+# Writer process
+db0.open(prefix_name, "w")
+obj.value = 124
+db0.commit()
+
+# Reader process - sees changes automatically
+db0.open(prefix_name, "r")
+assert obj.value == 124  # Updated value visible
+```
+
+### Change Data Capture
+
+Compare snapshots to identify changes:
+
+```python
+snap_before = db0.snapshot()
+# ... make changes ...
+snap_after = db0.snapshot()
 
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+# Find what changed
+new_items = db0.select_new(query, snap_before, snap_after)
+deleted_items = db0.select_deleted(query, snap_before, snap_after)
+modified_items = db0.select_modified(query, snap_before, snap_after)
+```
+
+### Singleton Pattern
+
+Create unique instances per prefix:
+
+```python
+@db0.memo(singleton=True)
+class AppConfig:
+    def __init__(self, version: str):
+        self.version = version
+
+# Only one instance can exist per prefix
+config = AppConfig("1.0.0")
+config_ref = db0.fetch(AppConfig)  # Same instance
+assert config is config_ref
+```
+
+---
+
+## Scalability
+
+dbzero is built for horizontal scalability using proven distributed systems patterns:
+
+- **Data Partitioning** - Automatic sharding across multiple prefixes
+- **Multiple-Handshake Transactions** - Ensures data integrity across distributed systems
+- **Cache Locality** - Indexes can be bound to specific contexts for optimal performance
+
+---
+
+## Configuration
+
+Configure dbzero during initialization:
+
+```python
+db0.init(
+    storage_dir="/path/to/data",
+    config={
+        'autocommit': True,
+        'autocommit_interval': 1000,  # milliseconds
+        'cache_size': 1024 * 1024 * 100  # 100MB
+    }
+)
+```
+
+Or configure specific prefixes:
+
+```python
+db0.open("my-prefix", "rw", autocommit=False)
+```
+
+---
+
+## Use Cases
+
+- **Web Applications** - Unified state management for backend services
+- **Data Processing Pipelines** - Efficient batch operations with transaction support
+- **Event-Driven Systems** - Change data capture and time travel for auditing
+- **Distributed Systems** - Built-in support for multi-process synchronization
+- **AI Applications** - Simplified state management for AI agents and workflows
+
+---
+
+## Documentation
+
+For comprehensive documentation, visit: **[dbzero.io](https://dbzero.io)**
+
+Topics covered:
+- API Reference
+- Tutorials
+- Data Modeling Patterns
+- Performance Optimization
+- Migration Guides
+
+---
+
+## Commercial Support
 
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+Need help building large-scale solutions with dbzero?
 
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
+We offer:
+- Custom UI and admin tools
+- System integrations
+- Expert consulting and architectural reviews
+- Performance tuning
+
+Contact us at: **info@dbzero.io**
+
+---
+
+## Why dbzero?
+
+### Traditional Stack
+```
+Application Code
+    ↓
+ORM Layer
+    ↓
+Database Layer
+    ↓
+Caching Layer
+    ↓
+Storage
+```
+
+### With dbzero
+```
+Application Code + dbzero
+    ↓
+Storage
+```
+
+By eliminating intermediate layers, dbzero reduces complexity, improves performance, and accelerates development—all while providing the reliability and features you expect from a database system.
+
+---
 
 ## License
-For open source projects, say how it is licensed.
 
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3). See `LICENSE` for the full text.
+
+- If you modify and run this software over a network, you must offer the complete corresponding source code to users interacting with it (AGPLv3 §13).
+- Redistributions must preserve copyright and license notices and provide source.
+
+For a short summary, see `COPYING`. For attribution details, see `NOTICE`.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please contact us at **info@dbzero.io** for guidelines and contribution process.
+
+---
+
+## Support
+
+- **Documentation**: [dbzero.io](https://dbzero.io)
+- **Email**: info@dbzero.io
+- **Issues**: Contact us for bug reports and feature requests
+
+---
+
+**Start coding as if you have infinite memory. Let dbzero handle the rest.**

From 4f1d0ee8d6a8c82c87587fbcceb8c642614057a4 Mon Sep 17 00:00:00 2001
From: Wojtek <wskozlowski@dbzero.io>
Date: Thu, 4 Dec 2025 12:37:52 +0100
Subject: [PATCH 2/5] readme

---
 README.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index fa577d10..24faa20f 100644
--- a/README.md
+++ b/README.md
@@ -10,7 +10,15 @@
 
 **dbzero** lets you code as if you have infinite memory. Inspired by a thought experiment from *Architecture Patterns with Python* by Harry Percival and Bob Gregory, dbzero handles the complexities of data management in the background while you work with simple Python objects.
 
-The result is a simplified application stack that can eliminate the need for separate databases, ORMs, and caching layers—reducing development time by up to **80%**.
+dbzero implements the **DISTIC memory** model:
+- **D**urable - Data persists automatically across application restarts
+- **I**nfinite - Work with data as if memory constraints don't exist
+- **S**hared - Multiple processes can access and share the same data
+- **T**ransactions - Full ACID transaction support for data integrity
+- **I**solated - Operations are isolated and thread-safe
+- **C**omposable - A single process can integrate multiple memory partitions (prefixes) to suit its specific requirements
+
+The result is a simplified application stack that can eliminate the need for separate databases, ORMs, and caching layers—reducing development time by up to **80%** and, in some cases, enabling applications to run **hundreds of times faster**.
 
 ---
 

From 0f9efb168e13578242e9fe8da06d5bd1e2b49589 Mon Sep 17 00:00:00 2001
From: Wojtek <wskozlowski@dbzero.io>
Date: Thu, 4 Dec 2025 12:48:22 +0100
Subject: [PATCH 3/5] readme

---
 README.md | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 24faa20f..63e2af44 100644
--- a/README.md
+++ b/README.md
@@ -52,17 +52,20 @@ pip install dbzero
 ### Hello World Example
 
 ```python
+from dataclasses import dataclass
 import dbzero as db0
 
 @db0.memo(singleton=True)
+@dataclass
 class Root:
-    def __init__(self, greeting):
-        self.greeting = greeting
+    greeting: str
 
     def greet(self):
         print(self.greeting)
 
 if __name__ == "__main__":
+    db0.init(dbzero_root="./data")
+    
     if db0.exists(Root):
         print("Process started with data...")
         root = db0.fetch(Root)
@@ -353,10 +356,10 @@ Application Code
     ↓
 ORM Layer
     ↓
-Database Layer
-    ↓
 Caching Layer
     ↓
+Database Layer
+    ↓
 Storage
 ```
 
@@ -390,9 +393,9 @@ Contributions are welcome! Please contact us at **info@dbzero.io** for guideline
 
 ## Support
 
-- **Documentation**: [dbzero.io](https://dbzero.io)
+- **Documentation**: [docs.dbzero.io](https://docs.dbzero.io)
 - **Email**: info@dbzero.io
-- **Issues**: Contact us for bug reports and feature requests
+- **Issues**: https://github.com/dbzero-software/dbzero/issues
 
 ---
 

From 7ef04e6fb3c4e0306cfd714ae9950560f26a35c5 Mon Sep 17 00:00:00 2001
From: Wojtek <wskozlowski@dbzero.io>
Date: Thu, 4 Dec 2025 12:53:35 +0100
Subject: [PATCH 4/5] readme

---
 README.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/README.md b/README.md
index 63e2af44..833912e7 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,8 @@ if __name__ == "__main__":
 
 When the process exits, the application state is persisted automatically. The same data will be available the next time the app starts.
 
+**Note:** All objects linked to `Root` (and any objects they reference) are automatically managed by dbzero. There's no need for explicit conversions, fetching, or saving—dbzero handles persistence transparently for the entire object graph.
+
 ---
 
 ## Core Concepts

From 85d58d4c7f2db0e993b98759cc7d49ccd3d89ae5 Mon Sep 17 00:00:00 2001
From: Wojtek <wskozlowski@dbzero.io>
Date: Thu, 4 Dec 2025 12:59:41 +0100
Subject: [PATCH 5/5] Readme

---
 README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 833912e7..afb28e8f 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ dbzero implements the **DISTIC memory** model:
 - **D**urable - Data persists automatically across application restarts
 - **I**nfinite - Work with data as if memory constraints don't exist
 - **S**hared - Multiple processes can access and share the same data
-- **T**ransactions - Full ACID transaction support for data integrity
+- **T**ransactions - Transaction support for data integrity
 - **I**solated - Operations are isolated and thread-safe
 - **C**omposable - A single process can integrate multiple memory partitions (prefixes) to suit its specific requirements
 
@@ -31,6 +31,7 @@ The result is a simplified application stack that can eliminate the need for sep
 - **Efficient Caching** - Only accessed data is loaded into memory
 - **Time Travel** - Query historical states at any transaction point
 - **Horizontal Scalability** - Built-in support for data partitioning and sharding
+- **Custom Data Models** - Unlike traditional databases, dbzero allows you to define custom data structures that match your domain's needs, enabling not just constant speedup but algorithmic speedup (e.g., O(log N) → O(1))
 
 ### Developer Experience
 - **Invisible by Design** - Minimal API surface; write regular Python code
@@ -325,7 +326,7 @@ db0.open("my-prefix", "rw", autocommit=False)
 
 ## Documentation
 
-For comprehensive documentation, visit: **[dbzero.io](https://dbzero.io)**
+For comprehensive documentation, visit: **[docs.dbzero.io](https://docs.dbzero.io)**
 
 Topics covered:
 - API Reference