# rockstor/rockstor-core architecture

> Architecture diagram of the GitHub repository rockstor/rockstor-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rockstor/rockstor-core
- Repository: https://github.com/rockstor/rockstor-core

## Overview

##### Project type and purpose
- Rockstor is a full-stack, open-source NAS appliance built in Python/Django with a JavaScript-driven web UI and a CLI.
- It exposes RESTful APIs, manages BTRFS/ZFS volumes, services (NFS, SMB, iSCSI, SNMP, UPS), and Docker “Rock-ons.”

##### File structure
- Top-level “conf” + “etc” dirs define systemd, nginx, supervisord, PostgreSQL, and UPS configurations.
- “src/rockstor” contains:
- Django project (manage.py, settings.py, wsgi.py, urls.py)
- Two main Django apps:
– storageadmin: admin UI, models, views, templates, Backbone/Marionette front-end assets under static/js/templates & views.
– smart_manager: metrics collection, task scheduling, replication broker & consumer, internal REST views.
- CLI tools under cli/ invoking the same REST API.
- System modules under system/ abstract OS-level commands (disk, network, services, smartctl).
- Scripts for bootstrapping, DB prep, scheduled tasks (cron wrappers).
- Build and deployment: build.sh, gulpfile.js for JS assets, Poetry/pyproject.toml for Python deps.

##### README for additional insights
- Reinforces Django + BTRFS foundation, REST APIs, Docker plugin sub-system.
- Emphasizes community, extensibility via Rock-ons registry.

##### Main components and interactions
a. Clients
- Web Browser/UI: loads HTML/CSS/JS (Backbone on top of Django templates) → speaks JSON to REST API.
- CLI (`rock`): command-line wrapper around REST calls.
b. API Gateway
- Django REST Framework endpoints (storageadmin and smart_manager routers).
c. Business Logic
- storageadmin.app: CRUD models for pools, shares, users, services, API keys, plugins.
- smart_manager.app: collects metrics, runs scheduled tasks, replication sender/receiver, SNMP probes.
- python/system modules: abstract calls to OS tools (btrfs, zfs, network, services, smartd, samba, docker).
d. Data Layer
- PostgreSQL (configured via conf/postgresql_*.sql + pg_hba.conf).
- Django ORM migrations in both apps.
e. Scheduler & Workers
- Huey/cron (scheduled_tasks under scripts and smart_manager) for scrubs, snapshots, replication triggers.
f. Persistence & Filesystem
- BTRFS/ZFS volumes under /dev; file sharing via NFS/SMB/iSCSI.
g. External Services & Integration
- Nginx (reverse proxy to Gunicorn).
- Supervisord or systemd to manage Gunicorn, scheduler, watchers.
- Docker daemon for Rock-ons (plugins).
- UPS (via upssched), SNMP daemons.
h. Logging & Monitoring
- var/log/* for system logs, Rockstor logs.

##### Architectural patterns & design principles
- MVC: Django (models → views → templates & REST serializers).
- CLI & Web UI both reuse the same REST API (API-first design).
- Modular “system” layer isolates OS interactions.
- Asynchronous scheduling via Python tasks & cron wrappers.
- Front-end uses Backbone/Marionette modules, templates, and a single-page app pattern.

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Clients
  subgraph "Clients"
    Browser["Web Browser/JS UI"]:::client
    CLI["CLI (rock)"]:::client
  end

  %% API Gateway
  subgraph "API Gateway"
    Nginx["Nginx Reverse Proxy"]:::api
    Gunicorn["Gunicorn WSGI"]:::api
  end

  %% Django REST API
  subgraph "Django REST API"
    DRF["Django REST Framework"]:::api
  end

  %% Django Core
  subgraph "Django Project Core"
    manage["manage.py"]:::file
    settings["settings.py"]:::file
    urls["urls.py"]:::file
    wsgi["wsgi.py"]:::file
  end

  %% Applications
  subgraph "Django Apps"
    storage["storageadmin App"]:::app
    smart["smart_manager App"]:::app
    system["System Abstraction Layer"]:::app
  end

  %% Scripts & Scheduler
  subgraph "Scheduler & Workers"
    scripts["Scheduled Tasks & Scripts"]:::file
    Huey["Huey/Cron Jobs"]:::sched
  end

  %% Data Layer
  subgraph "Data Layer"
    Postgres["PostgreSQL"]:::data
    FS["BTRFS/ZFS Volumes"]:::data
  end

  %% External Services
  subgraph "External Services"
    Docker["Docker Daemon & Rock-ons"]:::ext
    NAS["NFS/SMB/iSCSI Services"]:::ext
    UPS["UPS (nut)"]:::ext
    SNMP["SNMP Daemon"]:::ext
  end

  %% Connections
  Browser -->|HTTP/JSON| Nginx
  CLI -->|HTTP/JSON| Nginx
  Nginx --> Gunicorn
  Gunicorn --> DRF
  DRF -->|API Calls| storage
  DRF -->|API Calls| smart
  storage -->|ORM| Postgres
  smart -->|ORM| Postgres
  storage -->|calls| system
  smart -->|calls| system
  system -->|manages| FS
  system -->|manages| NAS
  system -->|manages| Docker
  smart -->|probes| SNMP
  Huey -->|triggers| smart
  scripts -->|wraps| Huey

  %% Click Events
  click manage "https://github.com/rockstor/rockstor-core/blob/master/src/rockstor/manage.py"
  click settings "https://github.com/rockstor/rockstor-core/blob/master/src/rockstor/settings.py"
  click urls "https://github.com/rockstor/rockstor-core/blob/master/src/rockstor/urls.py"
  click wsgi "https://github.com/rockstor/rockstor-core/blob/master/src/rockstor/wsgi.py"
  click storage "https://github.com/rockstor/rockstor-core/tree/master/src/rockstor/storageadmin/"
  click smart "https://github.com/rockstor/rockstor-core/tree/master/src/rockstor/smart_manager/"
  click system "https://github.com/rockstor/rockstor-core/tree/master/src/rockstor/system/"
  click scripts "https://github.com/rockstor/rockstor-core/tree/master/src/rockstor/scripts/"

  %% Styles
  classDef client fill:#a8d0e6,stroke:#000
  classDef api fill:#b0e57c,stroke:#000
  classDef app fill:#f8b195,stroke:#000
  classDef data fill:#c5c6fa,stroke:#000
  classDef ext fill:#f67280,stroke:#000
  classDef sched fill:#ffcc5c,stroke:#000
  classDef file fill:#eeeeee,stroke:#666666,stroke-dasharray: 2 2
```
