Infrastructure

Architecture and infrastructure components of self-hosted Bilanc.

This page describes the architecture and infrastructure components that make up a self-hosted Bilanc deployment.

Architecture Overview

---

Infrastructure Components

Bilanc consists of several core services, each responsible for a specific layer of the platform:

Dashboard (Next.js)

Property	Value
Port	3000
Technology	Next.js
Purpose	User interface

The Dashboard is the primary user interface for Bilanc. It provides:

• Interactive analytics and visualizations
• Team and individual metrics views
• AI-powered insights display
• Configuration and settings management

API Server (FastAPI)

Property	Value
Port	8000
Technology	FastAPI (Python)
Purpose	Backend API

The API Server handles:

• All REST API requests from the Dashboard
• Authentication and authorization
• Database queries and data retrieval
• Background task dispatch to Celery

Workflow Orchestrator (Dagster)

Dagster consists of two components:

Dagster Webserver

Property	Value
Port	4000
Technology	Dagster
Purpose	Pipeline monitoring UI

Provides a web interface for:

• Monitoring pipeline runs
• Viewing job history and logs
• Manual job triggering
• Schedule management

Dagster Daemon

Property	Value
Port	Internal
Technology	Dagster
Purpose	Pipeline execution

Responsible for:

• Scheduling and executing data pipelines
• Running data ingestion from integrations
• Triggering dbt transformations
• Managing pipeline dependencies

Task Queue (Celery)

Property	Value
Port	Internal
Technology	Celery (Python)
Purpose	Background jobs

Handles asynchronous background jobs:

• AI insight generation
• Email notifications
• Long-running computations
• Webhook processing

Message Broker (Redis)

Property	Value
Port	6379
Technology	Redis
Purpose	Message queue

Acts as the message broker for Celery tasks:

• Task queue management
• Job result storage
• Inter-service communication

Primary Database (PostgreSQL)

Property	Value
Port	5432
Technology	PostgreSQL
Purpose	Data storage

Persists all application data:

• User accounts and settings
• Ingested metrics from integrations
• Transformed analytics data
• Application state

---

Data Flow

Ingestion Flow

1. Dagster Daemon runs scheduled pipelines
2. Pipelines fetch data from integrations (GitHub, Linear, Cursor)
3. Raw data is stored in PostgreSQL
4. dbt transformations process raw data into analytics models

Request Flow

1. User accesses the Dashboard
2. Dashboard makes API requests to the API Server
3. API Server queries PostgreSQL for data
4. Results are returned and rendered in the Dashboard

Background Processing Flow

1. API Server dispatches tasks to Redis
2. Celery Worker picks up tasks from Redis
3. Worker processes tasks (AI generation, emails, etc.)
4. Results are stored in PostgreSQL or sent to external services

---

External Services

Integrations

Bilanc connects to external services to ingest data:

Service	Purpose
GitHub	Pull requests, commits, reviews, releases
GitLab	Merge requests, commits, pipelines
JIRA	Issues, sprints, project tracking
Linear	Issues, projects, cycles

AI Provider

Bilanc uses an AI provider for generating insights:

Provider	Models
OpenAI	GPT-4o, GPT-4, GPT-3.5
Anthropic	Claude 3.5, Claude 3
Google AI	Gemini Pro

Email Service

Bilanc uses Resend for:

• Scheduled report delivery
• Notification emails
• User invitations

---

Cloud vs. Self-Hosted

The Bilanc architecture is largely the same for both Cloud and Self-hosted deployments. This ensures self-hosted instances benefit from:

• Continuous improvements from cloud development
• Battle-tested components under real load
• Consistent feature parity

---

Network Requirements

Service	Direction	Purpose
Dashboard	Inbound	User access
Dagster	Inbound (optional)	Admin pipeline monitoring
Integrations	Outbound	GitHub, Linear, Cursor API access
AI Provider	Outbound	OpenAI, Anthropic, or Google AI API
Email	Outbound	Resend API

If you are interested in the self-hosting version, please get in touch with us at [e-mail] or book a demo.