Flipt v2 Demo - TravelCo

A comprehensive demonstration of Flipt v2 feature management platform showcasing a travel booking application with webapp (React), hotel (Python) and admin services (Go) using feature flags with both client-side and server-side SDK patterns.

Warning

This is a demonstration project designed to showcase Flipt's feature flag capabilities and integration patterns. It is not intended for production use and does not follow production best practices (e.g., authentication, data persistence, error handling, security measures, etc.). The goal is to demonstrate various ways to integrate and use Flipt across different programming languages and architectures.

Overview

This demo represents TravelCo, a fictional travel company's booking platform that uses Flipt feature flags to control various aspects of the user experience and service functionality.

SDK Architecture:

Client-Side SDKs (Webapp & Admin Service): Evaluate flags directly in the browser/client, fetching flag state and evaluating locally for low-latency decisions
Server-Side SDK (Hotel Service): Evaluates flags on the server via direct API calls to Flipt, suitable for backend services and sensitive business logic

Architecture

┌──────────────────────────────────────────────────────────┐
│                         Browser                          │
│         Webapp (Client-Side SDK - React)                 │
└────────────────────────┬─────────────────────────────────┘
                         │
                         ▼
┌──────────────────────────────────────────────────────────┐
│                    Nginx (Port 4000)                     │
│  - Serves webapp static files                            │
│  - Proxies /api/* → hotel-service:8000                   │
│  - Proxies /internal/v1/* → flipt:8080                   │
└─────────────┬──────────────────────┬─────────────────────┘
              │                      │
              │                      │
    ┌─────────▼────────┐   ┌─────────▼────────┐
    │   Hotel Service  │   │   Flipt v2       │
    │  Python/FastAPI  │──►│  (Port 8080)     │◄────┐
    │  (Server SDK)    │   │                  │     │
    │   (Port 8000)    │   │                  │     │
    └─────────┬────────┘   └──┬────┬──────┬───┘     │
              │               │    │      │         │
              ▲               │    │      │         │
    ┌─────────┴────────┐      │    │      └───────┐ │
    │  Admin Service   │      │    │              │ │
    │    Go/HTTP       │──────┘    │    ┌─────────▼─┴───┐
    │ (Client SDK)     │           │    │    Gitea      │
    │   (Port 8001)    │           │    │  (Port 3000)  │
    └─────────┬────────┘           │    │Feature Flags  │
              │                    │    └───────────────┘
              │                    │
              │                    └────┐
              │                         │
              │                    ┌────▼──────────┐
              │                    │  Prometheus   │
              │                    │  (Port 9090)  │
              │                    │   Metrics &   │
              │                    │   Analytics   │
              │                    └───────────────┘
              │
              │                ┌────────────┐
              └────────────────►   Jaeger   │
                               │(Port 16686)│
                               │Distributed │
                               │  Tracing   │
                               └────────────┘

Services

1. Webapp (React)

Port: 4000
Technology: React 19, Vite, TypeScript
Flipt Client: @flipt-io/flipt-client-react (client-side SDK)
SDK Type: Client-side - Evaluates flags in the browser for instant UI updates without reloads
Feature Flags:
- sale (boolean): Show/hide promotional banner
- theme (variant): Dynamic hero background based on season
User Experience:
- Browse hotels with dynamic pricing and availability
- Confirmation dialog before booking to prevent accidental reservations
- Real-time booking status with confirmation numbers
Telemetry: OpenTelemetry metrics exported to Prometheus

2. Hotel Service (Python)

Port: 8000
Technology: Python 3.12, FastAPI, Uvicorn
Flipt Client: flipt (Python SDK - server-side)
SDK Type: Server-side - Makes API calls to Flipt for each evaluation, suitable for backend business logic
API Documentation: OpenAPI/Swagger UI at root endpoint (/)
Feature Flags:
- price-display-strategy (variant): Control price presentation
  - per-night: Show price per night
  - total: Show total price
  - with-fees: Show price with fees breakdown
  - dynamic: Show dynamic pricing with savings
- real-time-availability (boolean): Enable live room availability
- loyalty-program (boolean): Show loyalty discounts (10% off)
- instant-booking (boolean): Immediate vs pending confirmations
Performance Optimization: Uses Flipt batch evaluation API to evaluate real-time-availability and loyalty-program flags in a single request, reducing network overhead
Telemetry: Full OpenTelemetry integration (traces + metrics)

3. Admin Service (Go)

Port: 8001
Technology: Go 1.25
Flipt Client: flipt-client-go (client-side SDK with streaming support)
SDK Type: Client-side - Fetches and caches flag state locally, with streaming updates for near real-time flag changes
API Documentation: OpenAPI/Swagger UI at root endpoint (/)
Feature Flags:
- auto-approval (boolean): Automatically approve low-risk bookings
- approval-tier (variant): Multi-level approval workflows
  - standard: Standard approval process
  - premium: Premium approval for higher-value bookings
  - vip: VIP approval for luxury bookings
Features:
- View all bookings (pending, confirmed, rejected)
- Approve/reject bookings with feature flag evaluation
- Automatically update booking status in hotel-service
- Generate confirmation numbers for approved bookings
- Real-time flag updates via streaming (5-second polling)
- Intelligent approval routing based on booking value and hotel category
Telemetry: Full OpenTelemetry integration (traces + metrics)

4. Flipt (Feature Management)

Port: 8080
Version: v2
Features:
- Git-based feature flag storage (via Gitea)
- Analytics storage in Prometheus
- Authentication via OIDC (Gitea)
- Environment: onoffinc
- Namespaces: default (webapp & hotel service), admin (admin service)

5. Gitea (Git Server & CI/CD)

Port: 3000
Purpose: Git-based storage for feature flags and CI/CD automation
Credentials: admin:password
Repository: onoffinc/features
Features:
- Git-based feature flag version control
- Gitea Actions for automated testing and validation
- Pull request workflows for flag configuration validation

6. Gitea Actions Runner

Container: gitea_act_runner
Purpose: Execute CI/CD workflows for automated testing
Features:
- Docker-in-Docker (DinD) support for building and testing
- Automatic registration with Gitea instance
- On-demand workflow execution for pull requests
Workflow: .gitea/workflows/lint.yaml
- Triggered on pull request events
- Downloads and installs Flipt CLI
- Validates feature flag configuration with flipt validate
- Ensures flag definitions are correct before merging

7. Jaeger (Distributed Tracing)

Port: 16686
Purpose: Collect and visualize traces from all services
Protocol: OTLP over HTTP

8. Prometheus (Metrics & Analytics)

Port: 9090
Purpose: Store metrics and analytics data
Credentials: admin:password
Features:
- OTLP receiver enabled
- Flipt analytics storage
- Custom service metrics

Quick Start

Prerequisites

Docker & Docker Compose
Make (optional)

Note

This project expects gitea.docker.localhost to resolve to 127.0.0.1. Add the following to your /etc/hosts file if needed:

127.0.0.1 gitea.docker.localhost

Start the Demo

# Build all services
make build

# Start all services
make start

# Or using docker-compose directly
docker compose up -d

Stop the Demo

make stop

# Or using docker-compose directly
docker compose down -v

Accessing the Demo

Once started, you can access:

Webapp: http://localhost:4000 - TravelCo booking site
Hotel API: http://localhost:8000 - Hotel service REST API with interactive Swagger UI documentation
Admin Service: http://localhost:8001 - Admin booking management API with interactive Swagger UI documentation
Flipt UI: http://localhost:8080 - Feature flag management
Gitea: http://localhost:3000 - Git repository for flags
Jaeger: http://localhost:16686 - Distributed tracing
Prometheus: http://localhost:9090 - Metrics and analytics

Default Credentials: admin:password

Demo Scenarios

Scenario 1: Seasonal Sale Banner

Open the webapp at http://localhost:4000
Notice if the seasonal sale banner appears at the top
Go to Flipt UI at http://localhost:8080
Toggle the sale boolean flag on/off
Check the webapp to see the banner appear or disappear
Use this to control promotional campaigns

Scenario 2: Seasonal Theming

Open the webapp at http://localhost:4000
Notice the hero background changes based on the current month
Go to Flipt UI and modify the theme flag rules
See the changes reflected immediately in the webapp

Scenario 3: Price Display A/B Testing

Use the hotel service API
Search hotels with different entity IDs
Notice different price display strategies
In Flipt UI, change the price-display-strategy variant distributions
Search again in webapp and observe changes

Scenario 4: Progressive Feature Rollout

In Flipt UI, set instant-booking to disabled
Book a hotel via webapp - you'll see a confirmation dialog
Confirm the booking - status will be "pending"
Enable instant-booking flag in Flipt
Make another booking - status will be "confirmed"
View the rollout in Jaeger traces

Scenario 5: Loyalty Program Launch

Disable loyalty-program flag initially
Search hotels - no loyalty discounts shown
Enable flag for specific user segments
Search again - premium hotels show 10% discount

Scenario 6: Batch Flag Evaluation Performance

Open Jaeger at http://localhost:16686
Search for traces from the hotel-service
Find a hotel search trace and expand it
Notice the feature_flag.batch_evaluation span that evaluates both loyalty-program and real-time-availability flags in a single API call
Compare this to individual evaluations - batch evaluation reduces network overhead
In Flipt UI, toggle both flags on/off
Search hotels again and observe in Jaeger how both flags are evaluated together efficiently

Scenario 7: Admin Booking Approval Workflow

Book a hotel via webapp at http://localhost:4000 (without instant-booking enabled)
Open Admin Service at http://localhost:8001/api/bookings?status=pending
View pending bookings from the hotel service
Go to Flipt UI and switch to the admin namespace using the namespace dropdown in the top navigation
Configure auto-approval and approval-tier flags in the admin namespace
Set approval rules based on booking value (e.g., auto-approve under $500)
Approve a booking via POST /api/bookings/{id}/approve
Booking status is updated to "confirmed" with a confirmation number
View traces in Jaeger showing flag evaluation, approval flow, and PATCH update
Check the booking status via hotel service: GET /api/bookings/{id}

Scenario 8: Multi-tier Approval Strategy

Go to Flipt UI and switch to the admin namespace using the namespace dropdown in the top navigation
Configure approval-tier variant rules in the admin namespace
Set segments: high-value bookings (>$1000) → VIP tier
Set segments: premium hotels → Premium tier
Default bookings → Standard tier
Create bookings with different price points and hotels
Approve bookings via admin service to see tier assignment
Monitor in Prometheus: admin_booking_approvals_total by tier
Review traces in Jaeger to see how context affects tier evaluation

Scenario 9: Automated Flag Validation with Gitea Actions

Go to Gitea at http://localhost:3000 and log in (admin:password)
Navigate to onoffinc/features repository
Click on features.yaml and edit it
Make a change to the flag configuration (try introducing a syntax error) and save into a new branch
Create a pull request from your branch
Watch the Gitea Actions runner automatically trigger
Navigate to the Actions tab to see the workflow running
The workflow will:
- Check out the code
- Download and install Flipt CLI (v2.2.0)
- Run flipt validate to check flag configuration
If validation fails, the PR will show a failed check
Fix the configuration and push again to re-trigger validation
Once validation passes, the PR can be safely merged
This ensures only valid flag configurations reach production

This demonstrates how to use CI/CD to maintain flag configuration quality and prevent misconfigurations from breaking your feature flag infrastructure.

Feature Flags Configuration

Feature flags are organized by namespace:

Default Namespace (gitea/default-features.yaml): Webapp and hotel service flags
Admin Namespace (gitea/admin-features.yaml): Admin service flags

Default Namespace (`default`)

Boolean Flags:

sale: Seasonal sale banner (webapp)
real-time-availability: Live room availability updates (hotel service)
loyalty-program: Loyalty member discounts (hotel service)
instant-booking: Instant confirmation flow (hotel service)

Variant Flags:

theme: Seasonal hero backgrounds - city, beach, mountain, snowboard (webapp)
price-display-strategy: Price presentation - per-night, total, with-fees, dynamic (hotel service)

Segments:

winter, spring, summer, fall: Seasonal segments based on month
premium-users: Premium tier users
budget-users: Budget-conscious users

Admin Namespace (`admin`)

Boolean Flags:

auto-approval: Automatic booking approval for low-risk bookings

Variant Flags:

approval-tier: Multi-level approval - standard, premium, vip

Segments:

trusted-bookings: Low-risk bookings (≤$500)
high-value-bookings: High-value bookings (≥$1000)
premium-hotels: Premium/luxury hotel bookings

Observability

Metrics in Prometheus

Visit http://localhost:9090 and query:

# Hotel service metrics
hotel_searches_total
hotel_availability_checks_total
hotel_bookings_total
price_display_strategy_usage_bucket

# Admin service metrics
admin_booking_approvals_total
admin_booking_views_total

# Flipt metrics
flipt_evaluations_requests_total
flipt_evaluations_results_total

Traces in Jaeger

Visit http://localhost:16686:

Select service
Click "Find Traces"
Explore request flows and feature flag evaluations
View span details including flag values and timings

Flipt Analytics

Visit http://localhost:8080:

Navigate to Analytics section
View flag evaluation counts
See variant distribution breakdowns
Analyze flag performance over time

Modifying Feature Flags

Option 1: Via Flipt UI (Recommended)

Go to http://localhost:8080
Navigate to flags
Edit flag rules, variants, or segments
Changes are synced to Git automatically

Option 2: Via Git

Go to Gitea: http://localhost:3000
Navigate to onoffinc/features repository
Edit features.yaml
Commit and push changes
Flipt polls and updates automatically (30s interval)

Key Learnings

This demo showcases:

Multi-language Support: React (frontend), Python (backend), and Go (admin service) all using Flipt
Client-Side vs Server-Side SDKs:
- Client-Side (Webapp & Admin): Fetch flag state and evaluate locally for low latency, with streaming updates
- Server-Side (Hotel Service): Make API calls to Flipt for each evaluation, ideal for backend services
Multiple Flag Types: Boolean and variant flags with different use cases
Segmentation: Context-based targeting (seasonal, user tier, booking value)
Git-based Storage: Feature flags as code with version control
Full Observability: Traces, metrics, and analytics integration
Streaming Updates: Go client with real-time flag synchronization
Performance Optimization: Batch evaluation API to reduce network overhead (Python service evaluates multiple boolean flags in a single request)
CI/CD Integration: Automated flag validation with Gitea Actions to prevent configuration errors
Real-world Use Cases:

A/B testing (price strategies)
Progressive rollouts (instant booking)
Seasonal targeting (themes)
Premium features (loyalty program)
Intelligent approval routing (admin service)
Multi-tier workflows (approval tiers)
Efficient flag evaluation patterns (batch API)
Different SDK patterns for different architectural needs
Automated quality gates for flag configurations

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
admin-service		admin-service
flipt		flipt
gitea		gitea
hotel-service		hotel-service
prometheus		prometheus
webapp		webapp
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml

flipt-io/demo-v2

Folders and files

Latest commit

History

Repository files navigation