Building the backend behind BERT.

BERT is an AI-assisted behavioural assessment and reporting product. A user authenticates by email, provides profile context, completes an adaptive assessment and receives a rendered “Blueprint” that can be shared with others.

As Founding Engineer, I owned the backend system design across API boundaries, persistence, authentication, assessment state, deterministic scoring, report generation, email workflows, telemetry and Azure delivery.

The problem

The product needed to convert a long, stateful user journey into a dependable outcome. This was not a single request-response API: users might leave and return, require clarification questions, retry report generation or revisit an already completed Blueprint.

The backend therefore had to preserve journey state, make assessment decisions consistently, handle third-party dependencies and expose a stable contract to a mobile client.

Constraints that shaped the design

• Small founding team: architecture needed clear boundaries without microservice operational overhead.
• Sensitive data: email, personal information, location-derived context and assessment responses required controlled access and careful telemetry.
• Probabilistic AI: generated language could enrich presentation, but could not become the authority for scores.
• Interrupted journeys: the server—not transient mobile state—needed to decide where a returning user resumes.
• Environment isolation: DEV, UAT and PROD required separate application data while selected expensive services remained shared.

Architecture

The system is a modular monolith. FastAPI route modules expose versioned contracts while services own domain logic and SQLAlchemy models persist operational state. This choice kept deployment simple while preserving boundaries that can be extracted later if scale or team topology requires it.

Primary data flow

1. Email OTP verification creates an authenticated JWT session.
2. Profile and consent inputs are persisted through explicit API calls.
3. The assessment service creates a server-owned session and selects the next item or clarification probe.
4. Responses update evidence and adaptive session state.
5. A deterministic scoring stage produces structured behavioural output.
6. Azure OpenAI assists narrative rendering from structured facts; the stored Blueprint remains retrievable independently of the client session.

Key engineering decisions

Deterministic computation before generated narrative

This creates a clearer audit boundary, supports repeatable tests and makes fallbacks possible when the AI dependency is slow or unavailable.

Server-owned adaptive state

The `/next` contract lets the backend decide whether to return another item, advance the phase or finish. The client renders the instruction it receives instead of reimplementing assessment rules. This reduces divergence between platforms and enables reliable resume behaviour.

PostgreSQL as operational source of truth

Relational records suit users, consent versions, sessions, responses, reports and deletion workflows. JSON/JSONB supports selected evolving evidence structures without turning the entire model into unvalidated documents. Schema evolution is handled through migrations rather than manual database changes.

Versioned API evolution

Versioned assessment routes allowed adaptive-selection work to evolve while protecting active client journeys. This was preferable to silently changing semantics behind an existing mobile contract.

Authentication, privacy and administration

The platform uses OTP authentication and JWT access tokens. Rate limits protect OTP send and verification routes. Sensitive administration is separated from consumer authentication through Microsoft Entra validation, explicit role checks and audit events.

Account deletion spans public and in-app flows, verified ownership, transactional confirmation and controlled removal or retention according to the published policy. Generic telemetry excludes raw names, email addresses, personal data, prompts and assessment free text.

Cloud delivery and observability

DEV, UAT and PROD run in UK South with dedicated PostgreSQL servers, Key Vault configuration, managed identities, Application Insights and diagnostic settings. Selected shared services—including Azure OpenAI and Azure Communication Services—avoid unnecessary duplication.

Azure DevOps pipelines apply tests and environment-specific deployments. UAT and PROD can use approval gates. Health checks, migration verification and Application Insights signals support release confidence without logging private payloads.

Outcome

The architecture supported a cross-platform beta with 27 registered users and 20 completed Blueprints. More importantly, it produced a backend foundation that can resume journeys, evolve scoring versions, retrieve stored outputs and isolate environments without cloning the codebase.

These are beta-scale adoption measures, not performance claims. Load, latency and reliability targets should be established through production SLOs and repeatable tests as usage grows.

What I learned

• Persist the product journey explicitly; mobile navigation state is not workflow state.
• Keep deterministic business meaning outside generative components.
• Design deletion, consent and telemetry while modelling the core domain—not after launch.
• A modular monolith is often the right founding-team architecture when its boundaries are deliberate.
• Instrumentation is most useful when events answer defined operational and product questions.

← Back to case studies