Skip to content
FraiseQL v2.0.0-alpha

Example Applications

Learn FraiseQL by exploring complete, production-ready example applications.

Prerequisites

Section titled “Prerequisites”

Before running any example:

  • FraiseQL installed:
    Terminal window
    curl -fsSL https://fraiseql.dev/install.sh | sh
    # or: brew install fraiseql / cargo install fraiseql
  • PostgreSQL 14+ running locally or via Docker (docker run -p 5432:5432 postgres:16)
  • Node.js 18+ (for frontend examples)

When the development server starts successfully you will see:

$ fraiseql run
INFO  FraiseQL 2.x starting…
INFO  Schema compiled — 12 types, 8 queries, 4 mutations
INFO  Connected to PostgreSQL at localhost:5432/mydb
INFO  GraphQL endpoint: http://localhost:8000/graphql
INFO  GraphiQL playground: http://localhost:8000/graphiql

Start from a Template

Section titled “Start from a Template”

Not sure where to begin? Clone a working starter and extend it:

Minimal

SQLite, one table, no Docker. Boots in 10 seconds.

Terminal window
git clone https://github.com/fraiseql/fraiseql-starter-minimal
cd fraiseql-starter-minimal && fraiseql run

Blog API

PostgreSQL — users, posts, comments, tags, mutations. The schema used throughout the docs.

Terminal window
git clone https://github.com/fraiseql/fraiseql-starter-blog
cd fraiseql-starter-blog && docker compose up

SaaS Multi-Tenant

PostgreSQL + RLS + JWT. Two isolated tenants out of the box.

Terminal window
git clone https://github.com/fraiseql/fraiseql-starter-saas
cd fraiseql-starter-saas && docker compose up

Example Catalog

Section titled “Example Catalog”
ExampleDescriptionDatabaseComplexityTags
SaaS BlogMulti-tenant blog with posts, comments, and role-based access. Requires PostgreSQL (uses Row-Level Security)PostgreSQLIntermediateauth, RLS, CQRS
Federation E-CommerceProduct catalog, orders, and inventory across federated databasesPostgreSQL (federated)Intermediatefederation, saga
Real-Time CollaborationCollaborative document editing with live cursors and conflict resolutionPostgreSQLAdvancedWebSocket, CRDT
Real-Time AnalyticsEvent ingestion, metrics, and live dashboardsPostgreSQL + TimescaleDBIntermediatetime-series, streaming
Mobile Analytics BackendPush notifications, offline sync, and background jobs. Requires PostgreSQL (uses materialized views)PostgreSQLIntermediatemobile, jobs
SaaS Federation + NATSMulti-tenant SaaS with cross-service federation over NATSPostgreSQL + NATSAdvancedfederation, NATS
NATS Event PipelineEvent-driven pipeline with NATS subjects and durable consumersPostgreSQL + NATSAdvancedevents, NATS
Microservices ChoreographyService-to-service choreography with saga and compensating transactionsPostgreSQLAdvancedmicroservices, saga

Available Examples

Section titled “Available Examples”

1. SaaS Blog Platform (Multi-Tenant)

Section titled “1. SaaS Blog Platform (Multi-Tenant)”

What you’ll learn:

  • Multi-tenant architecture
  • Row-level security (RLS)
  • User authentication with JWT
  • Role-based access control (RBAC)
  • Subscription-based features

Features:

  • User accounts and profiles
  • Blog posts and comments
  • Multiple teams/organizations
  • Tenant-isolated data (requires PostgreSQL 14+)
  • Feature flags per subscription tier
  • Analytics dashboard

Technology Stack:

  • Backend: FraiseQL
  • Database: PostgreSQL (uses Row-Level Security)
  • Frontend: Next.js (React)
  • Authentication: JWT + Okta
  • Hosting: Docker + Kubernetes

Repository: github.com/fraiseql/examples/saas-blog-platform

Duration: 45 minutes to understand, 2-3 hours to deploy

2. Federation E-Commerce

Section titled “2. Federation E-Commerce”

What you’ll learn:

  • Federation across multiple databases
  • Saga pattern for distributed transactions
  • Product catalog management
  • Order processing pipeline
  • Inventory management
  • Payment processing

Features:

  • Product catalog (PostgreSQL)
  • Inventory tracking (PostgreSQL)
  • Order management (PostgreSQL)
  • Payment integration (Stripe)
  • Shipping integration (EasyPost)
  • Promotional codes and discounts
  • Order notifications (email + SMS)

Technology Stack:

  • Backend: FraiseQL
  • Databases: PostgreSQL (federated)
  • Frontend: Vue.js
  • Payment: Stripe API
  • Notifications: Twilio (SMS), SendGrid (Email)
  • Hosting: AWS (ECS + RDS)

Repository: github.com/fraiseql/examples/federation-ecommerce

Duration: 1 hour to understand, 4-5 hours to deploy

3. Real-Time Collaboration App

Section titled “3. Real-Time Collaboration App”

What you’ll learn:

  • WebSocket-based real-time updates
  • Conflict-free replicated data (CRDT)
  • Concurrent editing
  • Operational transformation
  • Presence indicators
  • Activity feeds

Features:

  • Collaborative document editing
  • Real-time cursors and selections
  • Version history with branching
  • Comments and mentions
  • Permissions and sharing
  • Activity feed
  • Undo/redo

Technology Stack:

  • Backend: FraiseQL
  • Database: PostgreSQL
  • Frontend: React + Yjs (CRDT)
  • Real-time: WebSocket (built-in to FraiseQL)
  • Hosting: Kubernetes

Repository: github.com/fraiseql/examples/realtime-collaboration

Duration: 1.5 hours to understand, 6+ hours to deploy

4. Real-Time Analytics

Section titled “4. Real-Time Analytics”

What you’ll learn:

  • Time-series data aggregation
  • Complex analytics queries
  • Reporting with materialized views
  • Data warehouse patterns
  • Dashboard APIs
  • Real-time metrics

Features:

  • Event ingestion pipeline
  • Metrics calculation
  • Funnel analysis
  • Cohort analysis
  • Custom dashboards
  • Data export
  • Real-time metrics

Technology Stack:

  • Backend: FraiseQL
  • Databases: PostgreSQL + TimescaleDB
  • Frontend: Grafana + Custom dashboards
  • Streaming: Apache Kafka (optional)
  • Hosting: Docker

Repository: github.com/fraiseql/examples/realtime-analytics

Duration: 1 hour to understand, 4 hours to deploy

5. Mobile Analytics Backend

Section titled “5. Mobile Analytics Backend”

What you’ll learn:

  • Push notifications
  • Offline-first sync
  • Background jobs
  • File uploads
  • Deep linking
  • Analytics tracking (requires PostgreSQL — uses materialized views)

Features:

  • User authentication
  • Profile management
  • Content sync
  • Push notifications
  • File uploads
  • Offline queue
  • Background jobs
  • Analytics

Technology Stack:

  • Backend: FraiseQL
  • Database: PostgreSQL (uses materialized views)
  • Mobile: React Native + Expo
  • Push: Firebase Cloud Messaging
  • Files: AWS S3
  • Jobs: Celery + Redis
  • Hosting: AWS

Repository: github.com/fraiseql/examples/mobile-analytics-backend

Duration: 45 minutes to understand, 3-4 hours to deploy

6. SaaS Federation + NATS

Section titled “6. SaaS Federation + NATS”

What you’ll learn:

  • Multi-tenant federation
  • Cross-service data composition
  • NATS pub/sub messaging
  • Durable consumers and fan-out

Features:

  • Multi-tenant SaaS with federated services
  • Cross-service GraphQL queries
  • Event-driven notifications via NATS
  • Tenant-scoped subscriptions

Technology Stack:

  • Backend: FraiseQL
  • Databases: PostgreSQL + NATS JetStream
  • Hosting: Docker + Kubernetes

Repository: github.com/fraiseql/examples/saas-federation-nats

Duration: 1 hour to understand, 4 hours to deploy

7. NATS Event Pipeline

Section titled “7. NATS Event Pipeline”

What you’ll learn:

  • NATS subjects and consumer groups
  • Durable consumers with JetStream
  • Event fan-out and filtering
  • Dead-letter queue handling

Features:

  • Event ingestion with NATS subjects
  • Durable consumers for reliability
  • Fan-out to multiple processors
  • DLQ for failed messages

Technology Stack:

  • Backend: FraiseQL
  • Databases: PostgreSQL + NATS JetStream
  • Hosting: Docker

Repository: github.com/fraiseql/examples/nats-event-pipeline

Duration: 45 minutes to understand, 2-3 hours to deploy

8. Microservices Choreography

Section titled “8. Microservices Choreography”

What you’ll learn:

  • Service-to-service choreography
  • Saga pattern with compensating transactions
  • Idempotent event handlers
  • Distributed audit trails

Features:

  • Order → Inventory → Payment → Shipping pipeline
  • Compensation on failure (inventory release, refunds)
  • Full event log for observability
  • Retry and DLQ handling

Technology Stack:

  • Backend: FraiseQL (multiple services)
  • Database: PostgreSQL
  • Messaging: NATS JetStream
  • Hosting: Docker Compose / Kubernetes

Repository: github.com/fraiseql/examples/microservices-choreography

Duration: 1 hour to understand, 4-5 hours to deploy

Quick Start Any Example

Section titled “Quick Start Any Example”

  1. Clone the example

    Terminal window
    git clone https://github.com/fraiseql/examples.git
    cd examples/saas-blog-platform

  2. Install dependencies

    Terminal window
    uv sync
    npm install

  3. Set up environment

    Terminal window
    cp .env.example .env
    # Edit .env with your credentials

  4. Start database

    Terminal window
    docker-compose up -d postgres

  5. Run migrations

    Terminal window
    confiture migrate

  6. Start development server

    Terminal window
    fraiseql run

  7. Verify the API is healthy

    Terminal window
    curl http://localhost:8080/health

    Expected response:

    {"status": "healthy", "database": "connected", "version": "0.9.0"}

  8. In another terminal, start frontend

    Terminal window
    cd frontend && npm run dev
    # Open http://localhost:3000

Run in Container

Section titled “Run in Container”
Terminal window
# Build image
docker build -t fraiseql-example .


# Run with Docker Compose
docker-compose up


# Open http://localhost:3000

Deploy to Cloud

Section titled “Deploy to Cloud”

Each example includes deployment instructions:

  • Docker Compose (local)
  • Kubernetes manifests (production)
  • Cloud deployment scripts (AWS, GCP, Azure)

See each example’s README.md for specific instructions.

Learning Path

Section titled “Learning Path”

Intermediate (Start here):

  1. SaaS Blog Platform (multi-tenancy, RLS, auth)
  2. Federation E-Commerce (federation, saga)
  3. Real-Time Analytics (time-series, materialized views)
  4. Mobile Analytics Backend (files + notifications + background jobs)

Advanced: 5. NATS Event Pipeline (event-driven, durable consumers) 6. SaaS Federation + NATS (cross-service federation) 7. Real-Time Collaboration (WebSocket, CRDT, OT) 8. Microservices Choreography (saga, compensation, distributed transactions)

Common Patterns Across Examples

Section titled “Common Patterns Across Examples”

Authentication & Authorization

Section titled “Authentication & Authorization”

All examples use JWT with role-based access control:

@fraiseql.query(requires_scope="read:posts")
def get_posts(user_id: ID) -> list[Post]:
    """Get posts visible to user."""
    pass

Soft Deletes

Section titled “Soft Deletes”

Examples show how to implement soft deletes:

@fraiseql.type
class Post:
    id: ID
    title: str
    deleted_at: datetime | None  # NULL = not deleted


@fraiseql.query(sql_source="v_post")
def get_posts() -> list[Post]:
    """Get non-deleted posts."""
    pass

Pagination

Section titled “Pagination”

Standard cursor-based pagination:

@fraiseql.query(sql_source="v_post")
def get_posts(
    first: int = 10,
    after: str | None = None
) -> Connection[Post]:
    """Paginate through posts."""
    pass

Error Handling

Section titled “Error Handling”

Consistent error handling across all examples:

@fraiseql.mutation
def create_post(title: str) -> Post:
    """Create post with validation."""
    if not title:
        raise ValueError("Title is required")
    # ...

Testing

Section titled “Testing”

All examples include test suites:

Terminal window
pytest tests/
# or
npm test

Contributing Examples

Section titled “Contributing Examples”

Have a great FraiseQL example?

  1. Fork github.com/fraiseql/examples
  2. Create your example in a new directory
  3. Include README.md with:
    • Description and learning objectives
    • Architecture diagram
    • Setup instructions
    • Deployment instructions
    • Key features explained
  4. Include tests and CI/CD configuration
  5. Submit pull request

Example Structure

Section titled “Example Structure”
your-example/
├── README.md           # Description, setup, deployment
├── .env.example        # Example environment file
├── pyproject.toml      # Python dependencies (uv)
├── package.json        # Node dependencies
├── tests/              # Test suite
├── app/                # FraiseQL backend
│   ├── main.py         # Entry point
│   ├── schema.py       # FraiseQL schema
│   ├── database/       # Database setup
│   └── ...
├── frontend/           # Frontend application
│   ├── pages/
│   ├── components/
│   └── ...
└── docker-compose.yml  # Local development

FAQ

Section titled “FAQ”

Q: Can I use these as production templates?

A: Yes! Examples are designed to be production-ready. They include:

  • Security best practices
  • Error handling
  • Comprehensive tests
  • CI/CD configuration
  • Deployment scripts

Q: Do I need to understand all examples?

A: No. Pick the one closest to your use case and dig deep. Other patterns are similar and you’ll pick them up quickly.

Q: Can I combine patterns from multiple examples?

A: Absolutely! That’s the learning goal. Understand individual patterns, then combine them for your app.

Q: Are examples updated with new FraiseQL versions?

A: Yes. We maintain all examples with the latest FraiseQL release.

Q: Where do I ask questions about an example?

A:

  • Each example repo has a GitHub Discussions section
  • Join our Discord for real-time help
  • Check Troubleshooting guide

SaaS Blog Platform

Start with multi-tenancy and RLS — the most common SaaS pattern.

E-Commerce API

Learn federation and saga patterns for distributed transactions.

Real-Time Collaboration

Explore WebSocket subscriptions and conflict resolution with OT.

Analytics Platform

Build time-series pipelines and live dashboards with NATS.