> ## Documentation Index
> Fetch the complete documentation index at: https://bilanc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
flowchart TB
    Browser[User Browser]
    
    subgraph SelfHosted [Self-hosted Bilanc]
        Dashboard["Next.js Dashboard<br/>:3000"]
        Dagster["Dagster Webserver<br/>:4000"]
        API["FastAPI API Server<br/>:8000"]
        Redis["Redis<br/>Celery Broker"]
        Worker[Celery Worker]
        Daemon[Dagster Daemon]
        DB[(PostgreSQL)]
    end
    
    Browser --> Dashboard
    Browser --> Dagster
    Dashboard --> API
    API --> Redis
    Redis --> Worker
    API --> DB
    Daemon --> DB
    Worker --> DB
    
    Worker --> Integrations
    Daemon --> Integrations
    Daemon --> AI
    Worker --> AI
    Worker --> Email
    
    subgraph External [External Services]
        Integrations["GitHub / GitLab / JIRA / Linear"]
        AI[AI Provider]
        Email[Resend Email Service]
    end
```

***

## 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](https://resend.com) 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                          |

<Tip>
  If you are interested in the self-hosting version, please get in touch with us at [support@bilanc.co](mailto:support@bilanc.co) or book a [demo](https://calendly.com/0x-s13i/bilanc-15-min-customer-discovery-call).
</Tip>