BigBase Documentation

Everything you need to build and scale applications with BigBase. Single-binary backend platform with Auth, Database, Storage, Functions, Messaging, Deploy, Realtime, and Git Repos.

Quick Start

Download the binary and start the server. BigBase runs as a single binary with zero external dependencies.

$ go run . serve --port 8080 --db bigbase.db

Open /admin/ to access the admin dashboard. Register an account and start building.

For Google OAuth support:

$ go run . serve --port 8080 --db bigbase.db --google-client-id YOUR_ID --google-client-secret YOUR_SECRET

Build from source

BigBase requires Go 1.22+.

$ git clone https://github.com/danielvm-git/bigbase
$ cd bigbase
$ go build -o bigbase .
$ ./bigbase serve --port 8080

Configuration

Flags

Flag	Default	Description
--port	8080	HTTP server port
--db	bigbase.db	SQLite database path
--google-client-id		Google OAuth client ID
--google-client-secret		Google OAuth client secret

Database

By default BigBase uses SQLite. To switch to PostgreSQL, rename or symlink bigbase.db to a PostgreSQL connection string (coming in a future release).

CLI Reference

Command	Description
`bigbase serve`	Start the HTTP server (flags: --port, --db, --google-client-id, --google-client-secret)
`bigbase version`	Show the current version
`bigbase status`	Show kernel and component status
`bigbase components list`	List all registered ECC components
`bigbase help`	Show help text

Admin UI

BigBase ships with a full-featured admin dashboard at /admin/.

Pages

Route	Description
`#/`	Dashboard with system stats, charts, and activity feed
`#/data`	Data Studio — browse database collections and records
`#/sql`	SQL Editor — run arbitrary SQL queries
`#/users`	User management — list and delete users
`#/repos`	Git Repos — CRUD for Git repositories
`#/deploy`	Deployments — Git-based deployment with CI/CD
`#/storage`	Storage — file upload, download, and management
`#/messaging`	Messaging — email, SMS, and push notifications
`#/functions`	Functions — serverless JavaScript runtime
`#/forge`	Forge — issue tracker and Kanban board
`#/cici`	CI/CD — workflow configuration and run logs
`#/monitoring`	Monitoring — system metrics, logs, and alerts

API Reference

All API endpoints are served under /api/. Authentication is handled via JWT tokens set as HTTP-only cookies.

Auth

Method	Path	Description
POST	`/api/auth/login`	Sign in with email and password
POST	`/api/auth/register`	Create a new account
GET	`/api/auth/me`	Get current user info
GET	`/api/auth/users`	List all users (requires auth)
DELETE	`/api/auth/users/{id}`	Delete a user (requires auth)
GET	`/api/auth/oauth/google`	Initiate Google OAuth flow

Database

Method	Path	Description
GET	`/api/collections/`	List all table-like collections
GET	`/api/collections/{name}`	Get records from a collection
POST	`/api/sql`	Execute arbitrary SQL query

Storage

Method	Path	Description
POST	`/api/storage/upload`	Upload a file
GET	`/api/storage/files`	List all files
GET	`/api/storage/files/{id}`	Download a file
DELETE	`/api/storage/files/{id}`	Delete a file

Functions

Method	Path	Description
GET	`/api/functions`	List all functions
POST	`/api/functions`	Create a new function
PUT	`/api/functions/{id}`	Update a function
DELETE	`/api/functions/{id}`	Delete a function
POST	`/api/functions/{id}/run`	Execute a function

Messaging

Method	Path	Description
POST	`/api/messaging/email`	Send an email
POST	`/api/messaging/sms`	Send an SMS
POST	`/api/messaging/push`	Send a push notification
GET	`/api/messaging/messages`	List message history

Deploy

Method	Path	Description
GET	`/api/deploy`	List all deployments
POST	`/api/deploy`	Create a new deployment

Git

Method	Path	Description
GET	`/api/git/repos`	List all repos
POST	`/api/git/repos`	Create a repo
DELETE	`/api/git/repos/{id}`	Delete a repo

Monitoring

Method	Path	Description
GET	`/api/monitoring/metrics`	System metrics (CPU, memory, goroutines)
GET	`/api/monitoring/logs`	Application logs
GET	`/api/monitoring/alerts`	Alert configurations
POST	`/api/monitoring/alerts`	Create an alert

Architecture

BigBase uses the Entity-Component-Construct (ECC) pattern. This is a modular architecture where each backend feature is a pluggable Component that registers with a central Kernel.

Key Concepts

Kernel — Central lifecycle manager. Discovers components, starts/stops them, manages an event bus.
Component — A self-contained module implementing a feature (e.g., Auth, Database, Storage). Each component has Init → Start → Stop lifecycle.
Event Bus — Components communicate via events, not direct imports. This keeps them decoupled and individually testable.

$ bigbase components list

Components are registered in main.go before kernel start. Each component can emit and listen to events from other components. For example, the Auth component emits user:created when a new user registers, and other components can react to it.

Auth

Built-in authentication with email/password and Google OAuth. JWT tokens are set as HTTP-only cookies. The --google-client-id and --google-client-secret flags configure Google OAuth.

Database

SQLite by default. Access your data through the Data Studio at #/data or the SQL Editor at #/sql. The SQL Editor supports arbitrary SQL queries with result display.

Storage

File upload and management. Upload files through the admin UI or the API. Files are stored on disk and served with proper MIME types.

Functions

Serverless JavaScript runtime. Write functions in JavaScript, trigger them via HTTP or a cron schedule. View execution logs and results in the admin UI.

Messaging

Send email, SMS, and push notifications through a single API. Message history is stored in the database.

Deploy

Git-based deployment system. Link a Git repository, specify a branch, and deploy with one click. Auto-polls for status updates.

Realtime

WebSocket-based realtime events. Subscribe to database changes, system events, and custom channels at /realtime.