Architecture

Visual representations of FraiseQL’s architecture, data flow, and component interactions.

System Overview

graph TD
  subgraph CLIENTS
    web["Web App"]
    mobile["Mobile App"]
    cli["CLI Tool"]
    analytics["Analytics"]
  end

  subgraph FRAISEQL
    subgraph RequestHandler["Request Handler"]
      auth["Auth"]
      cache["Cache"]
      ratelimit["Rate Limit"]
      metrics["Metrics"]
    end

    subgraph QueryExecutor["Query Executor"]
      parser["Parser"]
      planner["Planner"]
      exec["Executor"]
    end

    subgraph DataLayer["Data Layer"]
      pool["Connection Pool"]
      viewrouter["View Router"]
      funcaller["Function Caller"]
    end
  end

  subgraph POSTGRESQL
    tables["tb_ Tables (Write)"]
    views["v_ Views (Read)"]
    functions["fn_ Functions (Mutations)"]
    projections["tv_ Tables (Projections)"]
    indexes["Indexes"]
  end

  web -- "GraphQL" --> auth
  mobile -- "GraphQL" --> auth
  cli -- "GraphQL" --> auth
  analytics -- "Arrow Flight" --> auth

  auth --> cache --> ratelimit --> metrics --> parser
  parser --> planner --> exec

  exec --> pool
  exec --> viewrouter
  exec --> funcaller

  pool --> tables
  viewrouter --> views
  funcaller --> functions
  tables --> projections --> indexes

CQRS Data Flow

graph LR
  subgraph WRITE_SIDE["WRITE SIDE"]
    mutation["Mutation"]
    fn_create["fn_create()\n(SQL Function)"]
    tb_user["tb_user\n(Base Table)"]
    sync["sync_tv_user()"]
  end

  subgraph READ_SIDE["READ SIDE"]
    query["Query"]
    v_user["v_user\n(SQL View)"]
    tv_user["tv_user\n(Projection)"]
  end

  response["Response\nJSON"]

  mutation --> fn_create --> tb_user --> sync
  query --> v_user --> tv_user

  sync -- "Syncs to" --> tv_user
  tv_user --> response

View Composition

graph TD
  subgraph Composed["Composed Views"]
    v_comment["v_comment\njsonb_build_object()"]
  end

  subgraph Intermediate["Intermediate Views"]
    v_post["v_post\njsonb_build_object()"]
    v_user["v_user\njsonb_build_object()"]
  end

  subgraph BaseTables["Base Tables"]
    tb_post["tb_post\n(id, title, content, fk_user, ...)"]
    tb_user["tb_user\n(id, name, email, bio, ...)"]
  end

  v_comment -- "references" --> v_post
  v_comment -- "references" --> v_user
  v_post -- "joins" --> tb_post
  v_user -- "joins" --> tb_user

Compilation Pipeline

graph LR
  subgraph INPUT
    schema["schema.py\n(Python Code)"]
    config["fraiseql.toml\n(Configuration)"]
  end

  subgraph PARSING
    py_parser["Python\nParser"]
    loader["Config\nLoader"]
  end

  subgraph ANALYSIS
    analyzer["Type\nAnalyzer"]
    types["Types\n(User, Post, Comment)"]
    queries["Queries\n(user(), posts())"]
    mutations["Mutations\n(create, update, delete)"]
  end

  subgraph GENERATION
    gen["Code\nGenerator"]
    sql["SQL Views\n(v_*.sql)"]
    rust["schema.compiled.json"]
    graphql["GraphQL Schema\n(schema.gql)"]
  end

  subgraph OUTPUT
    migrations["db/migrations/"]
    binary["fraiseql run\n(compiled schema)"]
    schema_out["schema/"]
  end

  schema --> py_parser
  config --> loader

  py_parser --> analyzer
  loader --> analyzer

  analyzer --> types
  analyzer --> queries
  analyzer --> mutations

  types --> gen
  queries --> gen
  mutations --> gen

  gen --> sql
  gen --> rust
  gen --> graphql

  sql --> migrations
  rust --> binary
  graphql --> schema_out

Observer Event Flow

graph TD
  subgraph WRITE_OPERATION["WRITE OPERATION"]
    mutation["Mutation"]
    fn["fn_create_order()\n(SQL Function)"]
    insert["INSERT INTO\ntb_order"]
  end

  subgraph OBSERVER_SYSTEM["OBSERVER SYSTEM"]
    subgraph EventQueue["Event Queue"]
      event1["Event 1\norder_created"]
      event2["Event 2\norder_shipped"]
      event3["Event 3\npayment_failed"]
    end

    subgraph ConditionEval["Condition Evaluator"]
      condition["condition: total > 1000"]
      result["Match"]
    end

    subgraph ActionDispatch["Action Dispatcher"]
      webhook["Webhook\nPOST to external"]
      slack["Slack\n#sales channel"]
      email["Email\nto: sales@..."]
    end
  end

  external["External API"]
  slackapi["Slack API"]
  emailsvc["Email Service"]

  mutation -- "calls" --> fn
  fn -- "executes" --> insert

  insert -- "TRIGGER" --> EventQueue

  event1 -- "processes" --> condition
  event2 -- "processes" --> condition
  event3 -- "processes" --> condition

  condition --> result
  result -- "if matches" --> ActionDispatch

  webhook --> external
  slack --> slackapi
  email --> emailsvc

Request Lifecycle

graph TD
  client_request["Client Request"]
  http_server["HTTP Server"]
  auth["Auth Middleware"]
  auth_error["401 Unauthorized"]
  rate_limiter["Rate Limiter"]
  rate_error["429 Too Many Requests"]
  cache_lookup["Cache Lookup"]
  cache_hit["Cached Response"]
  gql_parser["GraphQL Parser"]
  validator["Validator"]
  validation_error["400 Bad Request"]
  planner["Query Planner"]
  executor["SQL Executor"]
  connection_pool["Connection Pool"]
  database["PostgreSQL"]
  response_builder["Response Builder"]
  cache_store["Cache Store"]
  json_response["JSON Response"]

  client_request --> http_server --> auth

  auth -- "if invalid" --> auth_error
  auth -- "if valid" --> rate_limiter

  rate_limiter -- "if exceeded" --> rate_error
  rate_limiter -- "if allowed" --> cache_lookup

  cache_lookup -- "if hit" --> cache_hit
  cache_lookup -- "if miss" --> gql_parser

  gql_parser --> validator
  validator -- "if invalid" --> validation_error
  validator -- "if valid" --> planner

  planner --> executor
  connection_pool -- "gets connection" --> executor
  executor -- "sends query" --> database

  database -- "returns data" --> response_builder
  response_builder --> cache_store --> json_response

  cache_hit -- "fast path" --> json_response
  auth_error -- "error path" --> json_response
  rate_error -- "error path" --> json_response
  validation_error -- "error path" --> json_response

How It Works

Detailed explanation of FraiseQL

CQRS Pattern

Data architecture and CQRS

View Composition

How views compose into entities