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 v2.1 starting…
INFO  Schema compiled — 12 types, 8 queries, 4 mutations
INFO  Connected to PostgreSQL at localhost:5432/mydb
INFO  GraphQL endpoint: http://localhost:8080/graphql
INFO  GraphiQL playground: http://localhost:8080/graphiql

Start from a Template

Section titled “Start from a Template”

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

Minimal

PostgreSQL, one table, no Docker. The fastest way to see FraiseQL running — clone fraiseql-starter-minimal and run fraiseql run.

Blog API

PostgreSQL — users, posts, comments, tags, mutations. The schema used throughout the docs. Clone fraiseql-starter-blog and run docker compose up.

SaaS Multi-Tenant

PostgreSQL + RLS + JWT. Two isolated tenants out of the box. Clone fraiseql-starter-saas and run docker compose up.

Example Catalog

Section titled “Example Catalog”
ExampleDescriptionDatabaseComplexityTags
Multi-Tenant SaaSOrganizations, projects, RLS, observers, REST + GraphQL. The reference example for production patternsPostgreSQL + NATSIntermediateauth, RLS, observers, REST
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
    fraiseql 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": "2.1.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)

REST and gRPC in Examples

Section titled “REST and gRPC in Examples”

All FraiseQL starters and examples serve REST and gRPC alongside GraphQL on port 8080 — no extra configuration is needed. Each example’s README.md notes which transport the example exercises. To test REST or gRPC endpoints in any example:

Terminal window
# REST — same resource names as GraphQL queries (default path: /rest/v1; configure via [rest] path)
curl http://localhost:8080/rest/v1/users


# gRPC — separate port (default 50052), requires grpcurl
grpcurl -plaintext localhost:50052 list
grpcurl -plaintext -d '{"limit": 10}' localhost:50052 fraiseql.BlogService/ListPosts

Schema annotations like @fraiseql.query (with fraiseql.config(sql_source="v_post") in the function body) automatically generate both the GraphQL resolver and the REST/gRPC endpoints. No separate REST or gRPC schema definition is needed.

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
def get_posts() -> list[Post]:
    """Get non-deleted posts."""
    return fraiseql.config(sql_source="v_post")

Pagination

Section titled “Pagination”

Standard cursor-based pagination using relay:

@fraiseql.query
def get_posts(
    first: int = 10,
    after: str | None = None
) -> list[Post]:
    """Paginate through posts (relay connection returned automatically)."""
    return fraiseql.config(sql_source="v_post", relay=True)

Error Handling

Section titled “Error Handling”

Validation and error handling live in the SQL function, not in the Python decorator body. The Python layer is compile-time only:

@fraiseql.mutation(sql_source="fn_create_post", operation="CREATE")
def create_post(title: str) -> Post:
    """Create post. fn_create_post validates title and returns an error status on failure."""
    pass

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.