Core Concepts

Core Concepts

Before diving into FlightStack, it helps to understand the key concepts that make up the platform.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     FlightStack Cloud                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Web App   │  │     API     │  │  Pipeline Scheduler │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
                            │ HTTPS
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Your Infrastructure                       │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Build Agent │  │ Build Agent │  │    Build Agent      │  │
│  │   (Mac)     │  │  (Linux)    │  │    (Windows)        │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Key Concepts

Organizations

An Organization is the top-level container in FlightStack. It groups together:

• Repositories
• Pipelines
• Build Agents
• Team Members
• Billing

Organizations can be:

• Personal - For individual developers
• Team - For companies and teams with multiple members

Organization
├── Repositories
│   ├── my-flutter-app
│   └── another-app
├── Pipelines
├── Build Agents
│   ├── Mac-Mini-Office
│   └── Linux-CI-Server
└── Members
    ├── owner@company.com (Admin)
    └── dev@company.com (Member)

Repositories

A Repository represents a connected GitHub repository. When you connect a repository:

1. FlightStack creates a webhook in GitHub
2. Push events are forwarded to FlightStack
3. Pipelines can be triggered based on these events

Key properties:

• Linked to a GitHub repository
• Can have multiple pipelines
• Stores secrets and environment variables

Build Agents

A Build Agent is a machine that executes your builds. Agents are self-hosted, meaning they run on your own hardware.

Self-Hosted

Run on your Mac, Linux server, or Windows PC

Always Available

No build minute limits or queuing

Secure

Your code stays on your infrastructure

Powerful

Use your fastest hardware for builds

Agent states:

• Online - Agent is running and ready to accept jobs
• Busy - Agent is currently executing a build
• Offline - Agent is not running (no heartbeat)
• Disabled - Agent is manually disabled

Capabilities: Each agent reports what it can build:

• iOS (requires macOS + Xcode)
• Android (requires Android SDK)
• Web (available on all platforms)

Pipelines

A Pipeline is a visual workflow that defines how your app is built and deployed. Pipelines consist of:

• Triggers - What starts the pipeline
• Jobs - What actions to perform
• Connections - The order of execution

     ┌──────────┐
     │ On Push  │  ← Trigger
     └────┬─────┘
          │
          ▼
     ┌──────────┐
     │Run Tests │  ← Job
     └────┬─────┘
          │
    ┌─────┴─────┐
    │           │
    ▼           ▼
┌────────┐ ┌────────┐
│Build   │ │Build   │  ← Parallel Jobs
│iOS     │ │Android │
└───┬────┘ └───┬────┘
    │          │
    ▼          ▼
┌────────┐ ┌────────┐
│Deploy  │ │Deploy  │  ← Deployment Jobs
│iOS     │ │Android │
└───┬────┘ └───┬────┘
    │          │
    └────┬─────┘
         │
         ▼
    ┌──────────┐
    │ Notify   │  ← Notification Job
    └──────────┘

Triggers

Triggers determine when a pipeline runs. Available triggers:

Trigger	Description	Use Case
Manual	Run on demand	Production deploys
On Push	Run when code is pushed	CI builds
On Tag	Run when a tag is created	Release builds
On PR	Run on pull requests	PR validation
Scheduled	Run on a cron schedule	Nightly builds

Jobs

Jobs are the individual tasks in a pipeline. Each job type has specific configuration options:

Build Jobs

• CI Build
• Build iOS
• Build Android

Quality Jobs

• Run Tests
• Code Analysis

Deploy Jobs

• Deploy iOS
• Deploy Android
• Deploy Web

Utility Jobs

• Notification
• Shell Script
• Webhook
• Manual Approval

Connections

Connections define the execution order between jobs. A job only runs after all its upstream jobs complete successfully.

• Sequential - One job after another
• Parallel - Multiple jobs at the same time
• Fan-out - One job triggers multiple downstream jobs
• Fan-in - Multiple jobs must complete before one continues

Pipeline Runs

A Pipeline Run is a single execution of a pipeline. Each run:

• Has a unique ID
• Records the trigger (push, manual, etc.)
• Tracks status of each job
• Stores logs and artifacts
• Reports overall status (success/failure)

Run states:

• Queued - Waiting for an agent
• Running - Currently executing
• Success - All jobs completed successfully
• Failed - One or more jobs failed
• Cancelled - Manually stopped

Artifacts

Artifacts are files produced by builds:

• IPA files - iOS app packages
• APK/AAB files - Android app packages
• Test reports - JUnit XML, coverage reports
• Build logs - Complete output from each step

Artifacts are stored and can be:

• Downloaded manually
• Passed to deployment jobs
• Retained for a configurable period

Secrets & Variables

Secrets are encrypted values for sensitive data:

• API keys
• Signing credentials
• Service account tokens

Variables are key-value pairs for configuration:

• Build modes
• Version numbers
• Feature flags

Both can be scoped to:

• Organization level
• Repository level
• Pipeline level

Data Flow

Here’s how data flows through a typical build:

1. Developer pushes code to GitHub
          │
          ▼
2. GitHub sends webhook to FlightStack
          │
          ▼
3. FlightStack identifies matching pipelines
          │
          ▼
4. Pipeline run is created and queued
          │
          ▼
5. Available agent picks up the job
          │
          ▼
6. Agent clones repo and executes steps
          │
          ▼
7. Artifacts uploaded, status reported
          │
          ▼
8. Deployment jobs run (if configured)
          │
          ▼
9. Notifications sent, run marked complete

Security Model

FlightStack follows a security-first approach:

• Code stays on your agents - We never access your source code
• Secrets are encrypted - Using AES-256 encryption at rest
• Agent tokens are unique - Each agent has its own auth token
• HTTPS everywhere - All communication is encrypted
• Audit logging - Track who did what and when

Next Steps

Now that you understand the core concepts:

• Quick Start - Get your first build running
• Build Agents - Learn more about agents
• Pipelines - Dive into pipeline configuration