BigBase

Single-binary, component-based BaaS platform using Entity-Component-Construct (ECC) architecture.

BigBase is an open-source Backend-as-a-Service platform built with Go. It packs Auth, Database, Storage, Functions, Messaging, Git Repos, CI/CD, Realtime, and Site hosting into a single binary — zero external dependencies required.

Built on the ECC pattern: a kernel discovers, starts, and connects independent components via an event bus. No direct imports between components.

• Runtime: Go 1.26.3+
• Database: SQLite (default, zero-CGO via modernc.org/sqlite) or PostgreSQL
• Linter: golangci-lint (development only)

The deploy runtime assumes certain binaries exist on the build/VPS host (node, npm, pnpm, python3, pip, uv, go, git). Historically a "missing tool on deploy host" defect recurred repeatedly (#179) because each tool was added as a one-off patch in a Go code path. These tools are now declared in toolchain.toml — the single source of truth for the deploy-host toolchain.

scripts/verify-toolchain.sh reads the contract and fails with a clear TOOLCHAIN_MISSING:<tool> / TOOLCHAIN_VERSION_TOO_LOW:<tool> message when a required binary is absent or below its declared minimum:

bash scripts/verify-toolchain.sh

The toolchain-parity CI job (.github/workflows/test-build-release.yml) provisions the same tools scripts/setup-vps.sh installs on the VPS and then runs the verifier — so a tool missing in CI is a tool that would be missing on the VPS, caught pre-deploy instead of mid-build.

Adding a tool: when you add a new exec.Command/exec.LookPath call in components/deploy/, add an entry under [tools.required] (always needed) or [tools.optional] (only for some app types) in toolchain.toml, set min to the real floor, and CI enforces it automatically.

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

Open http://localhost:8080 for the landing page, or http://localhost:8080/admin/ for the admin dashboard.

• ECC Architecture: Modular kernel + 19 pluggable components, event-bus communication.
• Multi-Tenant Auth: Email/password, Google OAuth, API keys, JWT, orgs, invites, roles.
• Auto CRUD + SQL: Collection-based REST API with filter/sort, SQL editor, PostgreSQL dual-driver.
• File Storage: Upload/download/delete with MIME detection.
• Git Repos: Bare repo management, SSH clone, GitHub App integration.
• Serverless Functions: JavaScript runtime (goja) with fetch, DB, env, request context, cron scheduling.
• CI/CD Pipelines: Git push → workflow engine → deploy.
• Realtime: WebSocket subscriptions with mutation event broadcasting.
• Messaging: Email (SMTP), SMS, Push, Webhook, Telegram providers.
• Site Hosting: Deploy web apps from GitHub, custom domains with TLS.
• Monitoring: Metrics (Prometheus), structured JSON logs, alerts, health checks, SSE events.
• Production Hardening: Three-layer security model — Ubuntu OS (UFW + fail2ban + unattended-upgrades), BigBase (systemd + alerts + backups), Contabo VPS (snapshots + health checks). See .agents/skills/harden-vps/SKILL.md.
• Admin UI: Embedded React SPA — 8 pages, dark mode, responsive.
• MCP Server: Model Context Protocol (SSE and stdio transports) for AI tool integration.

Config merge priority: CLI flags > environment variables > defaults.

BigBase = Kernel + 19 Components. Components communicate exclusively via the event bus — no direct imports between components.

See specs/tech-architecture/tech-stack.md for the full architecture diagram and event flow.

# Run tests
go test ./...

# Build binary
go build -o bigbase .

# Linting
golangci-lint run ./...

# Coverage report
go test -coverprofile=coverage.out ./... && go tool cover -func=coverage.out

# Preflight (build gate)
npm run preflight

1. Read CONVENTIONS.md for coding standards and conventions.
2. Read AGENTS.md for the agentic development workflow.
3. Fork, create a feature branch (fix/BUG-id or feat/story-id).
4. Commit using Conventional Commits.
5. Open a Pull Request.

MIT — see LICENSE for details.