diff --git a/packages/backend-rs/README.md b/packages/backend-rs/README.md
new file mode 100644
index 0000000000..467d66b39c
--- /dev/null
+++ b/packages/backend-rs/README.md
@@ -0,0 +1,114 @@
+A work-in-progress Firefish backend written in Rust
+
+Minimum supported Rust version (MSRV): 1.74
+
+Auto-generated documentation is at <https://docs.firefish.dev/backend_rs>
+
+# How to write the code
+
+Currently, there is no entrypoint in this project, and all functions are executed via Node-API.
+
+You need to apply the [`macros::export`] proc macro to export a function to the Node.js backend:
+
+```rust,ignore
+#[macros::export]
+pub fn to_be_exported(value: &str) -> i32 {
+    // You can also call other functions that are not exported
+    do_something();
+    42
+}
+
+fn do_something() {
+    do_other_thing();
+}
+```
+
+this code will be translated into this TypeScript code:
+
+```typescript
+export declare function toBeExported(value: string): number {
+    /* executes the compiled Rust function */
+}
+```
+
+You can also export `async` functions:
+
+```rust,ignore
+#[macros::export]
+pub async fn async_function() -> i32 {
+    some_async_task().await
+}
+```
+
+```typescript
+export declare function asyncFunction(): Promise<number> {
+    /* executes the compiled Rust function */
+}
+```
+
+You need to specify `object` attribute to export `struct`s:
+
+```rust,ignore
+#[macros::export(object)]
+pub struct Thing {
+    pub field_one: String,
+    pub field_two: Option<String>,
+}
+```
+
+```typescript
+export interface Thing {
+    fieldOne: string
+    fieldTwo: string | null
+}
+```
+
+# Update auto-generated files
+
+These files are auto-generated and are not intended for manual editing:
+- `packages/backend-rs/index.js`
+- `packages/backend-rs/index.d.ts`
+- [`packages/backend-rs/src/model/entity/*`](crate::model::entity)
+
+## Prerequisites
+
+1. `dev/config.env` (see `dev/config.example.env` for reference)
+2. PostgreSQL database listening on port `25432`
+3. Dev dependencies
+    - [GNU Make](<https://www.gnu.org/software/make/>)
+    - [sea-orm-cli](<https://www.sea-ql.org/SeaORM/docs/generate-entity/sea-orm-cli/>)
+
+## Update database entity
+
+Run the following command in the repository root directory
+
+```sh
+make entities
+```
+
+## Update `index.js` and `index.d.ts`
+
+Run the following command in the repository root directory
+
+```sh
+make napi
+```
+
+# Unit tests
+
+It is highly encouraged that you write unit tests and test the code yourself (there is no integration test at this point).
+
+## Prerequisites
+
+1. `dev/config.env` (see `dev/config.example.env` for reference)
+2. PostgreSQL and Redis/Valkey instances and the config file (`.config/default.yml`)
+3. Dev dependency
+    - [cargo-nextest](<https://nexte.st/>)
+
+## Run unit tests
+
+Run the following command in the repository root directory
+
+```sh
+pnpm run test:rs
+```
diff --git a/packages/backend-rs/src/lib.rs b/packages/backend-rs/src/lib.rs
index 1b9933fb8a..ff7a49a471 100644
--- a/packages/backend-rs/src/lib.rs
+++ b/packages/backend-rs/src/lib.rs
@@ -1,3 +1,5 @@
+#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md"))]
+
 pub mod config;
 pub mod database;
 pub mod federation;