Server

The modality server is an Axum HTTP server exposing an async-graphql Federation v2 subgraph. It handles resource persistence, folder organization, authentication, and assessment bundle management.

Architecture

graph LR
    Dart[Dart App] -->|FRB| Rust[Rust Sessions]
    Rust -->|RemoteBackend| GQL[GraphQL Server]
    GQL --> PG[(PostgreSQL)]
    GQL --> Oso[Oso Cloud]
    GQL -->|gRPC| Diag[Diagnostics Service]

The server sits between the Rust session layer and the database. RemoteBackend in the client makes GraphQL requests to persist and load resources.

Stack

Layer	Technology
HTTP	Axum
API	async-graphql (Federation v2 subgraph)
Database	PostgreSQL (sqlx)
Auth	Oso Cloud
gRPC	tonic (hand-written proto types)
Migrations	sqlx-cli

Configuration

Environment-based via Config::from_env():

Variable	Default	Purpose
DATABASE_URL	required	PostgreSQL connection string
PORT	4000	HTTP listen port
OSO_URL	https://cloud.osohq.com	Oso Cloud API endpoint
OSO_API_KEY	required	Oso Cloud API key
DIAGNOSTICS_GRPC_URL	optional	gRPC endpoint for diagnostics service

Startup

#[tokio::main]
async fn main() {
    let config = Config::from_env();
    let pool = PgPool::connect(&config.database_url).await?;
    sqlx::migrate!().run(&pool).await?;

    let oso = OsoClient::new(&config.oso_url, &config.oso_api_key);
    let resource_repo = ResourceRepository::new(pool.clone());
    let folder_repo = FolderRepository::new(pool.clone());
    let bundle_repo = AssessmentBundleRepository::new(pool.clone());
    let bundle_fetcher = GrpcBundleFetcher::new(&config.diagnostics_grpc_url);

    let schema = Schema::build(QueryRoot, MutationRoot, EmptySubscription)
        .data(resource_repo)
        .data(folder_repo)
        .data(bundle_repo)
        .data(oso)
        .data(bundle_fetcher)
        .enable_federation()
        .finish();

    let app = Router::new()
        .route("/graphql", post(graphql_handler))
        .route("/health", get(|| async { "ok" }))
        .route("/sdl", get(sdl_handler));

    axum::serve(listener, app).await?;
}

Request Flow

1. HTTP request arrives with X-Uid header (set by API gateway)
2. graphql_handler extracts AuthUser from headers (supports X-Impersonate-Uid for admin)
3. Auth guards check Oso Cloud permissions per resolver
4. Resolver executes database operation
5. For mutations: Oso Cloud facts are updated alongside database writes

Endpoints

Path	Method	Purpose
/graphql	POST	GraphQL endpoint
/health	GET	Health check
/sdl	GET	Federation SDL export

Related

• GraphQL — schema, queries, mutations
• Auth — Oso Cloud integration
• Resources — resource persistence and pagination
• Folders — folder organization
• Bundles — assessment algorithm data
• gRPC — diagnostics bundle fetcher