Türkçe: README.tr.md

Apeiron

A general-purpose data management engine that unifies version control, archiving, backup, synchronisation and integrity checking in a single core.

Apeiron treats a developer's repository, a musician's project and a family photo archive the same way: as snapshots of content-addressed, immutable objects. Backup, archive, sync and versioning are different policies over the same object graph, not four separate engines. It is local first: no core function needs a cloud, an account or an internet connection.

Status: Early development. Stage 0 (format and core) is done; Stage 1 (local MVP) is done; Stage 2 (remote and sync) is done; Stage 3 (developer and ecosystem) is done; Stage 4 (interfaces and multi-user) is done; Stage 5 (enterprise) is in progress. The apeiron command can already back up, sync, branch, merge, search and restore folders and import Git repositories, but there is no release or stable API yet. See docs/ROADMAP.md.

Core principles

#	Principle	In short
1	Generality	Git concepts belong to a plugin, not the core; no data type is the default
2	Local first	Everything works offline, without an account or a cloud
3	Data ownership	The storage format is open and documented (docs/FORMAT.md)
4	Integrity	Every object is verified with a cryptographic hash; corruption is never silent
5	Reversibility	Destructive operations can be undone; permanent deletion is a separate step
6	Secure defaults	Encryption, permissions and audit log are designed in from the start
7	Thin core	The core knows data, history and policy; domain meaning lives in plugins
8	API first	The CLI and all interfaces use the same public API as everyone else
9	Resource awareness	A Raspberry Pi 4 is a real target, not a test target
10	Progressive complexity	Simple tasks are simple; advanced control is not restricted

The full list and the requirements are in docs/VISION.md.

Architecture

flowchart TB
    UI["Interfaces<br/>CLI · Daemon · Desktop · Web · Mobile"]
    API["Public API<br/>Rust API · C ABI · SDKs"]
    SVC["Services<br/>Versioning · Archive · Backup · Sync · Search · Policy"]
    CORE["Core<br/>Object model · Storage engine · Integrity · Encryption"]
    STORE["Storage targets<br/>Local disk · External disk · Network · Remote"]
    PLUG["Plugins (WASM sandbox)<br/>Type driver · Storage backend · Importer/exporter · Hook"]
    UI --> API --> SVC --> CORE --> STORE
    PLUG -.-> SVC
    PLUG -.-> STORE

Loading

Each layer uses only the layer directly below it. Details: docs/ARCHITECTURE.md.

Layers and crates

Layer	Crate	Role	Status
Core	apeiron-core	Object model, chunking, pack/index files, refs and reflogs	In progress
Storage targets	apeiron-core, apeiron-remote	Folder (local or external disk), SFTP and S3 remotes	Done
Services	apeiron-services	Backup, restore, listing, diff, sync, merge, search and pruning old backups today	In progress
Public API	apeiron	Rust API for all operations (docs/API.md §8)	In progress
System calls	apeiron-sys	Operating system calls that need unsafe (Windows write-through)	Done
C ABI	apeiron-ffi	Stable C interface libapeiron with the header apeiron.h, and the Python SDK over it (docs/SDK.md); may use unsafe	Done
CLI	apeiron-cli	The apeiron command (docs/CLI.md)	In progress
Background service	apeiron-daemon	Scheduled jobs and the restore test (docs/DAEMON.md)	Done
Desktop interface	apeiron-server, apeiron-desktop	Pages, a local server and a window for backing up and restoring without the command line (docs/DESKTOP.md)	Done
Web interface	apeiron-server, apeiron-cli	The same pages served to other computers over TLS, to users with roles and their own backups (docs/WEB.md, docs/USERS.md)	Done
Git	apeiron-git	Import and export of Git repositories with the same commit ids (docs/GIT.md)	Done
Plugins	apeiron-plugin	WebAssembly plugin host; type drivers merge files (docs/PLUGIN.md)	Done

Crate names for planned layers are chosen when the layer is started.

Technology stack

Area	Choice	Status
Language	Rust (edition 2024, minimum 1.97); C only for the ABI	In use
Hashing	BLAKE3, keyed mode for object ids (blake3)	In use
Chunking	FastCDC 2020, average 1 MiB (fastcdc)	In use
Compression	zstd (zstd)	In use
Configuration	TOML (toml, serde)	In use
Errors	Typed errors (thiserror)	In use
Structured objects	Canonical CBOR (minicbor)	In use
Git compatibility	gitoxide (gix)	In use
Plugins	WebAssembly component model, Wasmtime	In use
Async runtime	Tokio (SFTP, S3 and the web server only; the core and the background service stay blocking)	In use
CI	GitHub Actions: fmt, clippy, tests on Linux x86_64/aarch64, macOS, Windows	In use

Why each choice was made: docs/DECISIONS.md.

Roadmap summary

Stage	Scope	Status
0. Format and core	Format specification, storage engine, integrity, Rust API draft	Done
1. Local MVP	CLI, snapshots, history, restore, local backup targets, tar, zip and 7z export	Done
2. Remote and sync	Daemon, encryption, SFTP/S3, sync, restore test	Done
3. Developer and ecosystem	Branch/merge, Git import/export, C ABI, Python SDK, plugins	Done
4. Interfaces and multi-user	Desktop and web UI, permissions, audit log, sharing	Done
5. Enterprise	Central identity, multi-tenant use, replication, high availability, immutable archive, compliance reports	In progress

Details and exit criteria: docs/ROADMAP.md.

Development

cargo fmt --all --check
cargo clippy --all-targets -- -D warnings
cargo test

Rules for code, commits and format changes: CONTRIBUTING.md.

Documentation

Document	Content
Vision	Product vision, principles, requirements, performance targets
Architecture	Layers, object model, data flows, plugin boundary, security model
Storage format	On-disk format specification, version 1
Decisions	Architecture decision records (ADR)
Roadmap	Stages 0–5, scope, exit criteria, current status
API	Design principles and specification of the public API
CLI	Every command of apeiron, its options and exit codes
SDK	The C ABI and the language SDKs
Background service	Scheduled jobs and the restore test
Sync	Folder sync between devices and conflict detection
Git	Importing a Git repository with its history and exporting it back
Branches	Branching and merging
Search	Finding files by name, metadata and text, also in the history
Plugins	WebAssembly plugins and type drivers
Text plugin	Merging text files line by line and showing their differences
Desktop interface	Backing up and restoring in a window, without the command line
Web interface	Using a backup server from a browser on another computer
Users and permissions	Several people on one backup server, each with their own backups
Audit log	A record of who did what in the web interface that cannot be changed unnoticed
Central identity	Signing in to the web interface through an organization's OpenID Connect identity provider
Multi-tenant use	Several organizations on one web server, each at its own address with its own repository, users and records
Replication	Keeping every backup on a second place and a standby server ready to take over
Immutable archive	Backups nobody can change or delete before the time they must be kept
Compliance reports	One document for auditors: what is backed up, whether it is whole, copied, protected and kept, and who had access
Sharing	Links that let someone without an account download a version, folder or file of a backup until they end
Performance	What the program was measured to do, and how to measure it again
User guide	Installation, daily backup, restore and the one-month test
Glossary	Terms with English–Turkish equivalents
Contributing	Development environment and rules
Security	Reporting vulnerabilities, security principles

Licence

Dual-licensed under either of

• MIT licence (LICENSE-MIT)
• Apache License, Version 2.0 (LICENSE-APACHE)

at your option. Unless you explicitly state otherwise, any contribution you submit is dual-licensed as above, without additional terms.