{"id":23125094,"url":"https://github.com/statisticsnorway/statbus","last_synced_at":"2026-05-25T07:02:28.665Z","repository":{"id":86589695,"uuid":"372819865","full_name":"statisticsnorway/statbus","owner":"statisticsnorway","description":"STATistical BUSiness register","archived":false,"fork":false,"pushed_at":"2026-05-20T22:43:34.000Z","size":195309,"stargazers_count":6,"open_issues_count":3,"forks_count":4,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-05-21T04:53:38.951Z","etag":null,"topics":["business","chadcn-ui","javascript","postgresql","register","sbr","statbus","statistical"],"latest_commit_sha":null,"homepage":"https://www.statbus.org/","language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statisticsnorway.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2021-06-01T12:21:02.000Z","updated_at":"2026-05-20T22:31:52.000Z","dependencies_parsed_at":"2023-09-22T20:10:12.384Z","dependency_job_id":"ec09d8c6-0d02-446e-bd7d-57d32233a6ed","html_url":"https://github.com/statisticsnorway/statbus","commit_stats":null,"previous_names":[],"tags_count":172,"template":false,"template_full_name":null,"purl":"pkg:github/statisticsnorway/statbus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fstatbus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fstatbus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fstatbus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fstatbus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statisticsnorway","download_url":"https://codeload.github.com/statisticsnorway/statbus/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statisticsnorway%2Fstatbus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33464012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["business","chadcn-ui","javascript","postgresql","register","sbr","statbus","statistical"],"created_at":"2024-12-17T08:12:31.294Z","updated_at":"2026-05-25T07:02:28.633Z","avatar_url":"https://github.com/statisticsnorway.png","language":"PLpgSQL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# STATBUS\n\n**STATistical BUSiness Registry** - A temporal database system for tracking business activity throughout history.\n\nDeveloped by [Statistics Norway (SSB)](https://www.ssb.no/) | Website: https://www.statbus.org/\n\n---\n\n## Quick Navigation\n\n**Choose your path based on your role:**\n\n### 📊 I want to **use** StatBus\n→ **[User Guide (doc/USAGE.md)](doc/USAGE.md)**\n- Load and manage business registry data\n- Access data via web interface or api\n- Generate reports and export data\n\n**→ Ready to integrate?** See **[Integration Guide (doc/INTEGRATE.md)](doc/INTEGRATE.md)** for REST API and PostgreSQL access\n\n### 🚀 I want to **deploy** StatBus\n→ **[Deployment Guide (doc/DEPLOYMENT.md)](doc/DEPLOYMENT.md)** - Single instance deployment (one country)  \n→ **[Cloud Guide (doc/CLOUD.md)](doc/CLOUD.md)** - Multi-tenant cloud deployment (for SSB staff)\n\n### 💻 I want to **develop** StatBus\n→ **[Development Guide (doc/DEVELOPMENT.md)](doc/DEVELOPMENT.md)**\n- Set up local development environment\n- Understand the codebase and architecture\n- Contribute to the project\n\n---\n\n## What is StatBus?\n\nStatBus 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.\n\n### Our Motto\n\n*Simple to Use, Simple to Understand, Simply Useful*\n\n### Key Features\n\n- **Temporal Data**: Track changes over time with valid_from/valid_to timestamps\n- **Row Level Security**: Integrated security at the database level\n- **REST API**: Automatic API generation from database schema via PostgREST\n- **Direct PostgreSQL Access**: Secure TLS-encrypted connections for SQL tools\n- **Modern Web Interface**: Built with Next.js and TypeScript\n- **Multi-tenant Ready**: SNI-based routing for hosting multiple instances\n\n---\n\n## Technology Stack\n\n### Backend\n\n- **[PostgreSQL 18+](https://www.postgresql.org)** - Database with temporal tables\n  - Row Level Security for access control\n  - [SQL Saga](https://github.com/veridit/sql_saga) for temporal foreign keys\n  - Custom JWT authentication integrated with PostgREST\n  \n- **[PostgREST 12+](https://postgrest.org/)** - Automatic REST API from database schema\n  \n- **[Caddy](https://caddyserver.com)** - Web server and reverse proxy\n  - Automatic HTTPS with Let's Encrypt\n  - Layer4 TLS proxy for PostgreSQL with SNI routing\n  - Cookie-to-header JWT conversion\n\n### Frontend\n\n- **[Next.js 15+](https://nextjs.org)** - React framework with App Router\n- **[TypeScript](https://www.typescriptlang.org)** - Type-safe JavaScript\n- **[Tailwind CSS](https://tailwindcss.com)** - Utility-first CSS framework\n- **[shadcn/ui](https://ui.shadcn.com)** - Component library\n- **[Highcharts](https://www.highcharts.com)** - Data visualization\n- **[Jotai](https://jotai.org)** - Atomic state management\n\n### Infrastructure\n\n- **[Docker](https://www.docker.com)** - Container runtime\n- **[Docker Compose](https://docs.docker.com/compose/)** - Multi-container orchestration\n- **[Crystal](https://crystal-lang.org)** - CLI tool and background worker\n\n---\n\n## Quick Start\n\n### For Users\n\n1. Get access to a StatBus instance from your administrator\n2. Log in via web browser\n3. Start loading data or querying via REST API or PostgreSQL\n4. Sample csv files available for each step from the GUI\n\nSee **[User Guide](doc/USAGE.md)** for detailed instructions.\n\n### For Administrators (Single Instance Deployment)\n\n```bash\ncurl -fsSL https://statbus.org/install.sh | bash\n```\n\nFor a specific version (pre-release or pinned):\n```bash\ncurl -fsSL https://statbus.org/install.sh | bash -s -- --version v2026.03.0-rc.25\n```\n\nThis downloads the `sb` CLI and bootstraps the full environment. Follow the on-screen prompts to configure your deployment.\n\nSee **[Deployment Guide](doc/DEPLOYMENT.md)** for detailed instructions.\n\n### For Developers (Local Development)\n\n```bash\n# Clone repository\ngit clone https://github.com/statisticsnorway/statbus.git\ncd statbus\n\n# Configure git hooks\ngit config core.hooksPath .githooks\n\n# Generate configuration\n./sb config generate\n\n# Start backend services\n./sb start all_except_app\n\n# Initialize database\n./dev.sh create-db\n./sb users create\n./sb migrate up\n\n# Run Next.js locally (in separate terminal)\ncd app\nnvm use\npnpm install\npnpm run dev\n```\n\nAccess at http://localhost:3000\n\nSee **[Development Guide](doc/DEVELOPMENT.md)** for detailed instructions.\n\n---\n\n## Architecture Overview\n\n**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.\n\n### The 1-2-3 Architecture\n\n**Level 1: Simple Web Interface**\n- Top-level actions: Import, Search/View/Edit, Report\n- Esoteric features hidden in command palette (cmd+k)\n- All UI calls use `/rest` endpoints (visible in browser, copyable to scripts)\n\n**Level 2: REST API Integration**\n- Same security as web (PostgreSQL RLS)\n- Copy web requests → automation scripts with API key\n- Type-safe TypeScript integration (auto-generated from DB schema)\n\n**Level 3: Direct PostgreSQL Access**\n- Same security (RLS enforced at database level)\n- No backend abstraction - full SQL capabilities\n- Each user = PostgreSQL role with same password everywhere\n\n### Key Design Principles\n\n✅ **Database IS the backend** - PostgREST exposes DB directly, avoiding custom backend code  \n✅ **Security in the database** - RLS ensures safety regardless of access method  \n✅ **Progressive disclosure** - Organizations adapt as they grow, never hitting backend limitations  \n✅ **Type safety from source** - Supabase tools export TypeScript types directly from schema  \n✅ **Transparent operations** - UI uses `/rest` so users can see and copy to scripts\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                        Browser                           │\n│  Level 1: Web UI (Import, Search/View/Edit, Report)      │\n│  Level 2: Copy /rest calls → scripts with API key        │\n└────────────────┬─────────────────────────────────────────┘\n                 │\n                 ↓ HTTPS (443) / PostgreSQL (5432)\n                 │ Level 3: Direct PostgreSQL (psql, DBeaver, etc.)\n┌────────────────┴─────────────────────────────────────────┐\n│              Caddy (Routing Layer)                       │\n│  • Routes /rest/* to PostgREST                           │\n│  • Routes / to Next.js                                   │\n│  • PostgreSQL TLS+SNI proxy (multi-tenant routing)       │\n└────┬────────────────────────┬──────────────────┬─────────┘\n     │                        │                  │\n     ↓                        ↓                  ↓\n┌─────────────┐      ┌──────────────────┐      Direct\n│  PostgREST  │      │  Next.js App     │      PostgreSQL\n│  (Level 2)  │      │  (Level 1 UI)    │      (Level 3)\n└─────┬───────┘      └──────────────────┘        │\n      │                                          │\n      └──────────────────┬───────────────────────┘\n                         ↓\n           ┌─────────────────────────────────────────┐\n           │      PostgreSQL Database                │\n           │  • Row Level Security (ALL levels)      │\n           │  • Each user = separate role            │\n           │  • Temporal tables + foreign keys       │\n           │  • Auto-materialized statistical_unit   │\n           └─────────────────────────────────────────┘\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eView Architecture Diagram\u003c/summary\u003e\n\n\u003cimg src=\"doc/diagrams/architecture.svg\" alt=\"StatBus Architecture\" style=\"max-width:100%;\"\u003e\n\u003c/details\u003e\n\nFor detailed architecture, see **[Service Architecture](doc/service-architecture.md)**.\n\n---\n\n## Documentation\n\n### User Documentation\n- **[User Guide](doc/USAGE.md)** - Using StatBus (loading data, querying, reports)\n- **[Integration Guide](doc/INTEGRATE.md)** - REST API and PostgreSQL access (advanced)\n\n### Administrator Documentation\n- **[Deployment Guide](doc/DEPLOYMENT.md)** - Single instance deployment\n- **[Cloud Guide](doc/CLOUD.md)** - Multi-tenant cloud deployment\n- **[Service Architecture](doc/service-architecture.md)** - Technical architecture details\n\n### Developer Documentation\n- **[Development Guide](doc/DEVELOPMENT.md)** - Local development setup\n- **[Conventions](CONVENTIONS.md)** - Backend coding standards (SQL, Crystal)\n- **[App Conventions](app/CONVENTIONS.md)** - Frontend coding standards (TypeScript, React)\n- **[AI Agents Guide](AGENTS.md)** - Guide for AI coding assistants\n\n---\n\n## Project Goals\n\nOur 2023-2025 technology modernization focused on:\n\n✅ **Easy to Get Started**\n- Wizard-guided local installation\n- Docker Compose for simple orchestration\n- Sample data for testing\n\n✅ **Fast Data Entry and Feedback**\n- Simple web forms for data creation\n- Fast batch processing\n- Immediate validation feedback\n\n✅ **Custom Reporting**\n- Simple report builder with graphs\n- Excel/CSV export\n- Historical queries (any point in time)\n\n✅ **Secure Database Integration**\n- Direct PostgreSQL access with TLS\n- REST API for web applications\n- Row Level Security for access control\n\n✅ **Adapted Data Models**\n- Insights from SSB and partner countries\n- Support for temporal foreign keys\n- Flexible classification systems\n\n---\n\n## Contributing\n\nWe welcome contributions! See **[Development Guide](doc/DEVELOPMENT.md)** for:\n- Setting up your development environment\n- Code conventions and style guides\n- Testing procedures\n- Pull request process\n\n---\n\n## Support and Community\n\n- **Issues**: https://github.com/statisticsnorway/statbus/issues\n- **Discussions**: https://github.com/statisticsnorway/statbus/discussions\n- **Website**: https://www.statbus.org\n- **Email**: Contact SSB via website\n\n---\n\n## License\nStatbus is licensed under the Apache License, Version 2.0.\nStatbus is an open-source Digital Public Good, aligned with the DPG Standard.\n\n---\n\n## Acknowledgments\n\nDeveloped by Statistics Norway (SSB) with contributions from partner statistical offices in Africa, Asia and Europe.\n\nSpecial thanks to all contributors and users who have helped shape StatBus into a modern, efficient business registry system.\nSpecial thanks also to manager(s) still believing in our project, even though we ended up being a few weeks delayed.\nThe delay has implied this releasy to be more robust and secure and smoother to install.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatisticsnorway%2Fstatbus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatisticsnorway%2Fstatbus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatisticsnorway%2Fstatbus/lists"}