# firenook-dev/firenook architecture

> Architecture diagram of the GitHub repository firenook-dev/firenook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/firenook-dev/firenook
- Repository: https://github.com/firenook-dev/firenook

## Overview

Firenook is a Rust-based local Firebase-compatible emulator preview. A developer starts a configured suite through the CLI; client SDKs then reach service-specific HTTP/gRPC fronts, which implement Firebase APIs over persistent Firestore state and native Auth, Storage, Rules, Pub/Sub, Tasks, Functions, and Extensions runtimes. Functions execute user JavaScript in supervised Node workers. The repository also includes a browser console and export/import support. README statements establish the product capabilities; several internal links below are dashed because the supplied source excerpts do not show their wiring.

Main entry points: [`crates/suite-runtime/src/lib.rs`](https://github.com/firenook-dev/firenook/blob/main/crates/suite-runtime/src/lib.rs) (Suite lifecycle), [`crates/grpc-front/src/service.rs`](https://github.com/firenook-dev/firenook/blob/main/crates/grpc-front/src/service.rs) (Firestore gRPC), [`crates/core-store/src/disk.rs`](https://github.com/firenook-dev/firenook/blob/main/crates/core-store/src/disk.rs) (Disk/WAL store), [`crates/rest-front/src/lib.rs`](https://github.com/firenook-dev/firenook/blob/main/crates/rest-front/src/lib.rs) (Firestore REST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and suite"]
  node_cli["CLI commands<br/>[main.rs]"]
  node_suitefront["Suite control API<br/>[lib.rs]"]
  node_suiteruntime["Suite lifecycle<br/>[lib.rs]"]
end

subgraph group_firestore["Firestore and rules"]
  node_grpc["Firestore gRPC<br/>[service.rs]"]
  node_rest["Firestore REST<br/>[lib.rs]"]
  node_webchannel["Firestore WebChannel<br/>[lib.rs]"]
  node_querycodec["Query decoding<br/>[query_codec.rs]"]
  node_queryengine["Query engine<br/>[query.rs]"]
  node_rulesengine["Rules evaluation<br/>[ast.rs]"]
  node_rulesruntime["Rules request state<br/>[request_history.rs]"]
end

subgraph group_services["Firebase services"]
  node_auth["Auth emulator<br/>[signin.rs]"]
  node_storage["Storage emulator<br/>[lib.rs]"]
  node_pubsub["Pub/Sub emulator<br/>[broker.rs]"]
  node_tasks["Cloud Tasks emulator<br/>[lib.rs]"]
  node_functions["Functions routes<br/>[server.rs]"]
  node_functionworker["Node worker<br/>[worker.rs]"]
  node_extensions["Extensions runtime<br/>[lib.rs]"]
end

subgraph group_runtime["Runtime and state"]
  node_store[("Disk/WAL store<br/>[disk.rs]")]
  node_export["Import/export format<br/>[entity.rs]"]
end

subgraph group_console["Developer console"]
  node_consoleapp["Console application<br/>[main.tsx]"]
  node_routes["Console routes<br/>[routeTree.gen.ts]"]
  node_consoleapi["Console API client<br/>[client.ts]"]
end

node_developer(("Developer"))
node_client(("Firebase client SDKs"))
node_nodecode(("User JS functions"))

node_developer -->|"runs commands"| node_cli
node_cli -.->|"starts suite"| node_suitefront
node_suitefront -.->|"controls lifecycle"| node_suiteruntime
node_client -.->|"calls gRPC"| node_grpc
node_client -.->|"calls REST"| node_rest
node_client -.->|"opens listen"| node_webchannel
node_grpc -.->|"decodes queries"| node_querycodec
node_querycodec -->|"builds queries"| node_queryengine
node_grpc -->|"runs pipeline"| node_queryengine
node_grpc -.->|"reads and writes"| node_store
node_rest -.->|"reads and writes"| node_store
node_webchannel -.->|"streams changes"| node_store
node_rulesruntime -.->|"evaluates rules"| node_rulesengine
node_rest -.->|"checks requests"| node_rulesruntime
node_grpc -.->|"checks requests"| node_rulesruntime
node_suiteruntime -.->|"starts service"| node_auth
node_suiteruntime -.->|"starts service"| node_storage
node_suiteruntime -.->|"starts service"| node_pubsub
node_suiteruntime -.->|"starts service"| node_tasks
node_suiteruntime -.->|"starts service"| node_functions
node_functions -.->|"supervises worker"| node_functionworker
node_nodecode -->|"executes in"| node_functionworker
node_suiteruntime -.->|"runs extensions"| node_extensions
node_developer -.->|"uses console"| node_consoleapp
node_consoleapp -->|"loads routes"| node_routes
node_routes -.->|"requests data"| node_consoleapi
node_export -.->|"imports and exports"| node_store

click node_cli "https://github.com/firenook-dev/firenook/blob/main/crates/cli/src/main.rs"
click node_suitefront "https://github.com/firenook-dev/firenook/blob/main/crates/suite-front/src/lib.rs"
click node_suiteruntime "https://github.com/firenook-dev/firenook/blob/main/crates/suite-runtime/src/lib.rs"
click node_grpc "https://github.com/firenook-dev/firenook/blob/main/crates/grpc-front/src/service.rs"
click node_rest "https://github.com/firenook-dev/firenook/blob/main/crates/rest-front/src/lib.rs"
click node_webchannel "https://github.com/firenook-dev/firenook/blob/main/crates/webchannel-front/src/lib.rs"
click node_querycodec "https://github.com/firenook-dev/firenook/blob/main/crates/grpc-front/src/query_codec.rs"
click node_queryengine "https://github.com/firenook-dev/firenook/blob/main/crates/query-engine/src/query.rs"
click node_rulesengine "https://github.com/firenook-dev/firenook/blob/main/crates/rules-engine/src/ast.rs"
click node_rulesruntime "https://github.com/firenook-dev/firenook/blob/main/crates/rules-runtime/src/request_history.rs"
click node_store "https://github.com/firenook-dev/firenook/blob/main/crates/core-store/src/disk.rs"
click node_export "https://github.com/firenook-dev/firenook/blob/main/crates/export-format/src/entity.rs"
click node_auth "https://github.com/firenook-dev/firenook/blob/main/crates/auth-front/src/ops/signin.rs"
click node_storage "https://github.com/firenook-dev/firenook/blob/main/crates/storage-front/src/lib.rs"
click node_pubsub "https://github.com/firenook-dev/firenook/blob/main/crates/pubsub-front/src/broker.rs"
click node_tasks "https://github.com/firenook-dev/firenook/blob/main/crates/tasks-front/src/lib.rs"
click node_functions "https://github.com/firenook-dev/firenook/blob/main/crates/functions-runtime/src/server.rs"
click node_functionworker "https://github.com/firenook-dev/firenook/blob/main/crates/functions-runtime/src/worker.rs"
click node_extensions "https://github.com/firenook-dev/firenook/blob/main/crates/extensions/src/lib.rs"
click node_consoleapp "https://github.com/firenook-dev/firenook/blob/main/console/src/main.tsx"
click node_routes "https://github.com/firenook-dev/firenook/blob/main/console/src/routeTree.gen.ts"
click node_consoleapi "https://github.com/firenook-dev/firenook/blob/main/console/src/api/client.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_suitefront,node_suiteruntime,node_client,node_nodecode toneBlue
class node_grpc,node_rest,node_webchannel,node_querycodec,node_queryengine,node_rulesengine,node_rulesruntime toneAmber
class node_auth,node_storage,node_pubsub,node_tasks,node_functions,node_functionworker,node_extensions toneMint
class node_store,node_export toneRose
class node_consoleapp,node_routes,node_consoleapi,node_developer toneIndigo
```

## Components

### Entry and suite

- [CLI commands](https://github.com/firenook-dev/firenook/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [Suite control API](https://github.com/firenook-dev/firenook/blob/main/crates/suite-front/src/lib.rs): `crates/suite-front/src/lib.rs`
- [Suite lifecycle](https://github.com/firenook-dev/firenook/blob/main/crates/suite-runtime/src/lib.rs): `crates/suite-runtime/src/lib.rs`

### Firestore and rules

- [Firestore gRPC](https://github.com/firenook-dev/firenook/blob/main/crates/grpc-front/src/service.rs): `crates/grpc-front/src/service.rs`
- [Firestore REST](https://github.com/firenook-dev/firenook/blob/main/crates/rest-front/src/lib.rs): `crates/rest-front/src/lib.rs`
- [Firestore WebChannel](https://github.com/firenook-dev/firenook/blob/main/crates/webchannel-front/src/lib.rs): `crates/webchannel-front/src/lib.rs`
- [Query decoding](https://github.com/firenook-dev/firenook/blob/main/crates/grpc-front/src/query_codec.rs): `crates/grpc-front/src/query_codec.rs`
- [Query engine](https://github.com/firenook-dev/firenook/blob/main/crates/query-engine/src/query.rs): `crates/query-engine/src/query.rs`
- [Rules evaluation](https://github.com/firenook-dev/firenook/blob/main/crates/rules-engine/src/ast.rs): `crates/rules-engine/src/ast.rs`
- [Rules request state](https://github.com/firenook-dev/firenook/blob/main/crates/rules-runtime/src/request_history.rs): `crates/rules-runtime/src/request_history.rs`

### Firebase services

- [Auth emulator](https://github.com/firenook-dev/firenook/blob/main/crates/auth-front/src/ops/signin.rs): `crates/auth-front/src/ops/signin.rs`
- [Storage emulator](https://github.com/firenook-dev/firenook/blob/main/crates/storage-front/src/lib.rs): `crates/storage-front/src/lib.rs`
- [Pub/Sub emulator](https://github.com/firenook-dev/firenook/blob/main/crates/pubsub-front/src/broker.rs): `crates/pubsub-front/src/broker.rs`
- [Cloud Tasks emulator](https://github.com/firenook-dev/firenook/blob/main/crates/tasks-front/src/lib.rs): `crates/tasks-front/src/lib.rs`
- [Functions routes](https://github.com/firenook-dev/firenook/blob/main/crates/functions-runtime/src/server.rs): `crates/functions-runtime/src/server.rs`
- [Node worker](https://github.com/firenook-dev/firenook/blob/main/crates/functions-runtime/src/worker.rs): `crates/functions-runtime/src/worker.rs`
- [Extensions runtime](https://github.com/firenook-dev/firenook/blob/main/crates/extensions/src/lib.rs): `crates/extensions/src/lib.rs`

### Runtime and state

- [Disk/WAL store](https://github.com/firenook-dev/firenook/blob/main/crates/core-store/src/disk.rs): `crates/core-store/src/disk.rs`
- [Import/export format](https://github.com/firenook-dev/firenook/blob/main/crates/export-format/src/entity.rs): `crates/export-format/src/entity.rs`

### Developer console

- [Console application](https://github.com/firenook-dev/firenook/blob/main/console/src/main.tsx): `console/src/main.tsx`
- [Console routes](https://github.com/firenook-dev/firenook/blob/main/console/src/routeTree.gen.ts): `console/src/routeTree.gen.ts`
- [Console API client](https://github.com/firenook-dev/firenook/blob/main/console/src/api/client.ts): `console/src/api/client.ts`

### Other components

- **Developer**
- **Firebase client SDKs**
- **User JS functions**

## Connections

- Developer → CLI commands: runs commands (evidence: `README.md`)
- CLI commands → Suite control API: starts suite
- Suite control API → Suite lifecycle: controls lifecycle
- Firebase client SDKs → Firestore gRPC: calls gRPC
- Firebase client SDKs → Firestore REST: calls REST
- Firebase client SDKs → Firestore WebChannel: opens listen
- Firestore gRPC → Query decoding: decodes queries
- Query decoding → Query engine: builds queries (evidence: `crates/grpc-front/src/query_codec.rs`)
- Firestore gRPC → Query engine: runs pipeline
- Firestore gRPC → Disk/WAL store: reads and writes
- Firestore REST → Disk/WAL store: reads and writes
- Firestore WebChannel → Disk/WAL store: streams changes
- Rules request state → Rules evaluation: evaluates rules
- Firestore REST → Rules request state: checks requests
- Firestore gRPC → Rules request state: checks requests
- Suite lifecycle → Auth emulator: starts service
- Suite lifecycle → Storage emulator: starts service
- Suite lifecycle → Pub/Sub emulator: starts service
- Suite lifecycle → Cloud Tasks emulator: starts service
- Suite lifecycle → Functions routes: starts service
- Functions routes → Node worker: supervises worker
- User JS functions → Node worker: executes in (evidence: `README.md`)
- Suite lifecycle → Extensions runtime: runs extensions
- Developer → Console application: uses console
- Console application → Console routes: loads routes (evidence: `console/src/main.tsx`)
- Console routes → Console API client: requests data
- Import/export format → Disk/WAL store: imports and exports
