STATistical BUSiness Registry - A temporal database system for tracking business activity throughout history.

Developed by Statistics Norway (SSB) | Website: https://www.statbus.org/

Choose your path based on your role:

→ User Guide (doc/USAGE.md)

• Load and manage business registry data
• Access data via web interface
• Generate reports and export data

→ Ready to integrate? See Integration Guide (doc/INTEGRATE.md) for REST API and PostgreSQL access

→ Deployment Guide (doc/DEPLOYMENT.md) - Single instance deployment (one country)
→ Cloud Guide (doc/CLOUD.md) - Multi-tenant cloud deployment (for SSB staff)

→ Development Guide (doc/DEVELOPMENT.md)

• Set up local development environment
• Understand the codebase and architecture
• Contribute to the project

StatBus is a statistical business registry that helps track business activity throughout history using temporal tables. It allows you to query the state of business units at any point in time.

Simple to Use, Simple to Understand, Simply Useful

• Temporal Data: Track changes over time with valid_from/valid_to timestamps
• Row Level Security: Integrated security at the database level
• REST API: Automatic API generation from database schema via PostgREST
• Direct PostgreSQL Access: Secure TLS-encrypted connections for SQL tools
• Modern Web Interface: Built with Next.js and TypeScript
• Multi-tenant Ready: SNI-based routing for hosting multiple instances

• PostgreSQL 18+ - Database with temporal tables

  • Row Level Security for access control
  • SQL Saga for temporal foreign keys
  • Custom JWT authentication integrated with PostgREST

• PostgREST 12+ - Automatic REST API from database schema

• Caddy - Web server and reverse proxy

  • Automatic HTTPS with Let's Encrypt
  • Layer4 TLS proxy for PostgreSQL with SNI routing
  • Cookie-to-header JWT conversion

• Next.js 15+ - React framework with App Router
• TypeScript - Type-safe JavaScript
• Tailwind CSS - Utility-first CSS framework
• shadcn/ui - Component library
• Highcharts - Data visualization
• Jotai - Atomic state management

• Docker - Container runtime
• Docker Compose - Multi-container orchestration
• Crystal - CLI tool and background worker

1. Get access to a StatBus instance from your administrator
2. Log in via web browser
3. Start loading data or querying via REST API or PostgreSQL

See User Guide for detailed instructions.

# Clone repository
git clone https://github.com/statisticsnorway/statbus.git
cd statbus

# Generate configuration
./devops/manage-statbus.sh generate-config

# Edit .env.config for your deployment
nano .env.config

# Start services
./devops/manage-statbus.sh start all

# Initialize database
./devops/manage-statbus.sh create-db-structure
./devops/manage-statbus.sh create-users
./cli/bin/statbus migrate up

See Deployment Guide for detailed instructions.

# Clone repository
git clone https://github.com/statisticsnorway/statbus.git
cd statbus

# Configure git hooks
git config core.hooksPath devops/githooks

# Generate configuration
./devops/manage-statbus.sh generate-config

# Start backend services
./devops/manage-statbus.sh start all_except_app

# Initialize database
./devops/manage-statbus.sh create-db-structure
./devops/manage-statbus.sh create-users
./cli/bin/statbus migrate up

# Run Next.js locally (in separate terminal)
cd app
nvm use
pnpm install
pnpm run dev

Access at http://localhost:3000

See Development Guide for detailed instructions.

StatBus uses a database-centric progressive disclosure architecture - NOT microservices. This design allows organizations to start simple and scale up as needs grow, without being constrained by backend abstractions.

Level 1: Simple Web Interface

• Top-level actions: Import, Search/View/Edit, Report
• Esoteric features hidden in command palette (cmd+k)
• All UI calls use /rest endpoints (visible in browser, copyable to scripts)

Level 2: REST API Integration

• Same security as web (PostgreSQL RLS)
• Copy web requests → automation scripts with API key
• Type-safe TypeScript integration (auto-generated from DB schema)

Level 3: Direct PostgreSQL Access

• Same security (RLS enforced at database level)
• No backend abstraction - full SQL capabilities
• Each user = PostgreSQL role with same password everywhere

✅ Database IS the backend - PostgREST exposes DB directly, avoiding custom backend code
✅ Security in the database - RLS ensures safety regardless of access method
✅ Progressive disclosure - Organizations adapt as they grow, never hitting backend limitations
✅ Type safety from source - Supabase tools export TypeScript types directly from schema
✅ Transparent operations - UI uses /rest so users can see and copy to scripts

┌──────────────────────────────────────────────────────────┐
│                        Browser                           │
│  Level 1: Web UI (Import, Search/View/Edit, Report)      │
│  Level 2: Copy /rest calls → scripts with API key        │
└────────────────┬─────────────────────────────────────────┘
                 │
                 ↓ HTTPS (443) / PostgreSQL (5432)
                 │ Level 3: Direct PostgreSQL (psql, DBeaver, etc.)
┌────────────────┴─────────────────────────────────────────┐
│              Caddy (Routing Layer)                       │
│  • Routes /rest/* to PostgREST                           │
│  • Routes / to Next.js                                   │
│  • PostgreSQL TLS+SNI proxy (multi-tenant routing)       │
└────┬────────────────────────┬──────────────────┬─────────┘
     │                        │                  │
     ↓                        ↓                  ↓
┌─────────────┐      ┌──────────────────┐      Direct
│  PostgREST  │      │  Next.js App     │      PostgreSQL
│  (Level 2)  │      │  (Level 1 UI)    │      (Level 3)
└─────┬───────┘      └──────────────────┘        │
      │                                          │
      └──────────────────┬───────────────────────┘
                         ↓
           ┌─────────────────────────────────────────┐
           │      PostgreSQL Database                │
           │  • Row Level Security (ALL levels)      │
           │  • Each user = separate role            │
           │  • Temporal tables + foreign keys       │
           │  • Auto-materialized statistical_unit   │
           └─────────────────────────────────────────┘

For detailed architecture, see Service Architecture.

• User Guide - Using StatBus (loading data, querying, reports)
• Integration Guide - REST API and PostgreSQL access (advanced)

• Deployment Guide - Single instance deployment
• Cloud Guide - Multi-tenant cloud deployment
• Service Architecture - Technical architecture details

• Development Guide - Local development setup
• Conventions - Backend coding standards (SQL, Crystal)
• App Conventions - Frontend coding standards (TypeScript, React)
• AI Agents Guide - Guide for AI coding assistants

Our 2023 technology modernization focused on:

✅ Easy to Get Started

• Wizard-guided local installation
• Docker Compose for simple orchestration
• Sample data for testing

✅ Fast Data Entry and Feedback

• Simple web forms for data creation
• Fast batch processing
• Immediate validation feedback

✅ Custom Reporting

• Simple report builder with graphs
• Excel/CSV export
• Historical queries (any point in time)

✅ Secure Database Integration

• Direct PostgreSQL access with TLS
• REST API for web applications
• Row Level Security for access control

✅ Adapted Data Models

• Insights from SSB and partner countries
• Support for temporal foreign keys
• Flexible classification systems

We welcome contributions! See Development Guide for:

• Setting up your development environment
• Code conventions and style guides
• Testing procedures
• Pull request process

• Issues: https://github.com/statisticsnorway/statbus/issues
• Discussions: https://github.com/statisticsnorway/statbus/discussions
• Website: https://www.statbus.org
• Email: Contact SSB via website

[License information to be added]

Developed by Statistics Norway (SSB) with contributions from partner statistical offices in Asia and Africa.

Special thanks to all contributors and users who have helped shape StatBus into a modern, efficient business registry system.