Initiate docusaurus website

Author: dannywillems

.gitignore

@@ -10,4 +10,7 @@ pkg/
 
 # Outputs of build-tests-webrtc
 cargo-build-test.json
-tests.tsv
+tests.tsv
+
+# Generated API docs should not be committed
+website/static/api-docs/

Makefile

@@ -259,3 +259,33 @@ postgres-setup: ## Set up PostgreSQL database for archive node
 	@sudo -u postgres psql -c "ALTER USER $(PG_USER) PASSWORD '$(PG_PW)'" 2>/dev/null || true
 	@sudo -u postgres createdb -O $(PG_USER) $(PG_DB) 2>/dev/null || true
 	@sudo -u postgres createdb -O $(PG_USER) $(PG_USER) 2>/dev/null || true
+
+# Documentation targets
+.PHONY: docs-install
+docs-install: ## Install documentation dependencies
+	@echo "Installing documentation dependencies..."
+	@cd website && npm install
+
+.PHONY: docs-build
+docs-build: docs-install ## Build the documentation website
+	@echo "Building documentation website..."
+	@cd website && npm run build
+	@echo "Documentation built successfully!"
+	@echo "Built files are in website/build/"
+
+.PHONY: docs-serve
+docs-serve: docs-install ## Serve the documentation website locally
+	@echo "Starting documentation server..."
+	@echo "Documentation will be available at: http://localhost:3000"
+	@cd website && npm start
+
+.PHONY: docs-build-serve
+docs-build-serve: docs-build ## Build and serve the documentation website locally
+	@echo "Serving built documentation at: http://localhost:3000"
+	@cd website && npm run serve
+
+.PHONY: docs-clean
+docs-clean: ## Clean documentation build artifacts
+	@echo "Cleaning documentation build artifacts..."
+	@rm -rf website/build website/.docusaurus
+	@echo "Documentation artifacts cleaned!"

website/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

website/README.md

@@ -0,0 +1,74 @@
+# OpenMina Documentation Website
+
+This directory contains the Docusaurus-based documentation website for OpenMina.
+
+## Quick Start
+
+### Development
+```bash
+# From project root
+make docs-serve
+# Or directly:
+cd website && npm start
+```
+
+### Build
+```bash
+# From project root  
+make docs-build
+# Or directly:
+cd website && npm run build
+```
+
+### Serve Built Site
+```bash
+# From project root
+make docs-build-serve
+# Or directly:
+cd website && npm run serve
+```
+
+## Structure
+
+### User-Focused Documentation
+The documentation is organized around three main user personas:
+
+- **Node Runners** (`docs/node-runners/`) - Installation, configuration, and operation guides
+- **Developers** (`docs/developers/`) - Architecture, codebase understanding, and contribution guides  
+- **Researchers** (`docs/researchers/`) - Protocol details, cryptography, and research materials
+
+### Configuration
+- `docusaurus.config.ts` - Main configuration file
+- `sidebars.ts` - Navigation structure for each user type
+- `src/pages/index.tsx` - Homepage
+- `src/components/` - Custom React components
+
+## Adding Documentation
+
+### New Pages
+1. Create markdown files in the appropriate directory (`docs/node-runners/`, `docs/developers/`, or `docs/researchers/`)
+2. Add frontmatter with title, description, and sidebar position:
+   ```yaml
+   ---
+   sidebar_position: 1
+   title: Page Title
+   description: Brief description for SEO
+   ---
+   ```
+3. Update `sidebars.ts` to include the new page in navigation
+
+### Editing Content
+Simply edit the markdown files - developers only need to modify markdown files, not the Docusaurus configuration.
+
+## Versioning
+
+The site supports versioning with the current version labeled as "develop". When tags are created, new documentation versions will be automatically deployed.
+
+## Available Commands
+
+From project root using Makefile:
+- `make docs-install` - Install dependencies
+- `make docs-build` - Build the website
+- `make docs-serve` - Start development server  
+- `make docs-build-serve` - Build and serve locally
+- `make docs-clean` - Clean build artifacts

website/docs/developers/architecture.md

@@ -0,0 +1,116 @@
+---
+sidebar_position: 1
+title: Architecture Overview
+description: Understand OpenMina's Redux-style state machine architecture and design principles
+slug: /developers/architecture
+---
+
+# OpenMina Architecture
+
+OpenMina follows a Redux-style state machine architecture for predictable, debuggable behavior. This design ensures that all state changes are traceable and the system behavior is deterministic.
+
+## Core Principles
+
+### State Machine Pattern
+
+OpenMina implements Redux principles adapted for a blockchain node:
+
+- **State** - Centralized, immutable data structure representing the entire node state
+- **Actions** - Events that trigger state changes throughout the system
+- **Enabling Conditions** - Guards that prevent invalid state transitions
+- **Reducers** - Pure functions that update state and dispatch new actions
+- **Effects** - Thin wrappers for service calls and side effects
+- **Services** - Separate threads handling I/O and heavy computation
+
+### Predictable State Management
+
+Every state change in OpenMina follows the same pattern:
+
+```rust
+// 1. Action is dispatched
+dispatch(SomeAction { data });
+
+// 2. Enabling condition is checked
+if enabling_condition_met(&state, &action) {
+    // 3. Reducer processes the action
+    let new_state = reducer(state, action);
+    
+    // 4. Effects may be triggered
+    trigger_effects(&new_state, &action);
+}
+```
+
+## Architecture Styles
+
+The codebase contains two architectural styles:
+
+### New Style (Recommended)
+- **Unified reducers** that handle both state updates and action dispatch
+- Single file per component containing all logic
+- Cleaner separation of concerns
+
+### Old Style (Being Migrated)
+- Separate reducer and effects files
+- Split between `*_reducer.rs` and `*_effects.rs`
+- Gradually being converted to new style
+
+## Component Structure
+
+### Core Components
+
+**Node** - Main node logic
+- Block production and validation
+- Transaction pool management
+- Consensus and blockchain state
+- RPC interface
+
+**P2P** - Networking layer
+- Dual transport: libp2p and WebRTC
+- Peer discovery and connection management
+- Message routing and validation
+
+**Ledger** - Blockchain state
+- Account state and transactions
+- Proof verification
+- Scan state management
+
+**Core** - Shared utilities
+- Common types and data structures
+- Cryptographic primitives
+- Configuration management
+
+### File Organization
+
+Each component follows consistent patterns:
+
+- `*_state.rs` - State definitions and data structures
+- `*_actions.rs` - Action types and event definitions
+- `*_reducer.rs` - State transition logic
+- `*_effects.rs` - Service interaction wrappers
+- `*_service.rs` - Service interface definitions
+- `summary.md` - Component documentation
+
+## Data Flow
+
+1. **External Events** (network messages, user commands) create actions
+2. **Actions** flow through the dispatch system
+3. **Enabling Conditions** validate whether actions can be processed
+4. **Reducers** compute new state based on current state and action
+5. **Effects** trigger service calls when state changes require external interaction
+6. **Services** handle async operations and generate new events
+
+## Key Benefits
+
+- **Debuggability** - Complete state history and action replay
+- **Testability** - Pure functions and predictable state changes  
+- **Maintainability** - Clear separation of concerns and data flow
+- **Performance** - Efficient state updates and selective processing
+
+## Development Guidelines
+
+- Use `bug_condition!` macro for theoretically unreachable code paths
+- Extract complex logic into state methods rather than bloating reducers
+- Prefer enabling conditions over error handling in reducers
+- Document component responsibilities in `summary.md` files
+
+For detailed implementation examples, see the component-specific documentation in the codebase.

website/docs/developers/why-openmina.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 2
+title: Why OpenMina?
+description: Learn about the motivation and benefits of developing OpenMina as an alternative Mina Protocol implementation
+---
+
+# Why are we developing the Open Mina node and the Mina Web node?
+
+## Diversifying the Mina ecosystem
+
+Just as with any blockchain, Mina benefits from increasing its diversity of
+nodes. It contributes to the network’s security, improves the protocol's clarity
+and ensures transparency across the blockchain. Additionally, it fosters an
+environment conducive to innovation while also safeguarding the integrity of all
+network participants.
+
+## Choosing Rust for safety and stability
+
+In systems responsible for safeguarding financial data, such as Mina, security
+and stability are of paramount importance. Hence, we have chosen Rust as our
+preferred language due to its exceptional levels of security, memory safety, and
+its ability to prevent concurrency issues, such as race conditions.
+
+## Increasing network resilience
+
+With multiple development teams actively engaged in creating various node
+implementations, the identification and resolution of bugs become a smoother
+process, diminishing the likelihood of negative impacts on the ecosystem. Since
+the burden of chain validation isn't concentrated in a single implementation,
+any bugs that do arise are effectively isolated within a limited subset of
+nodes, minimizing the potential impact on the entire blockchain.
+
+## More node options for the Mina community
+
+Lastly, users always benefit from having more options for running a Mina node.
+People may have different preferences when it comes to node implementations.
+Each programming language brings its own unique set of features to the table.
+The availability of a wide range of nodes empowers users to make choices that
+align with their specific preferences and requirements.

website/docs/intro.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 1
+---
+
+# Tutorial Intro
+
+Let's discover **Docusaurus in less than 5 minutes**.
+
+## Getting Started
+
+Get started by **creating a new site**.
+
+Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.
+
+### What you'll need
+
+- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
+  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
+
+## Generate a new site
+
+Generate a new Docusaurus site using the **classic template**.
+
+The classic template will automatically be added to your project after you run the command:
+
+```bash
+npm init docusaurus@latest my-website classic
+```
+
+You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.
+
+The command also installs all necessary dependencies you need to run Docusaurus.
+
+## Start your site
+
+Run the development server:
+
+```bash
+cd my-website
+npm run start
+```
+
+The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.
+
+The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.
+
+Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.