Assaliz
A multi-tenant platform for schools, student associations and campus operations. I led the platform architecture and backend implementation across identity, permissions, integrations and production controls.
Source code is private. The case study focuses on system boundaries, production constraints and implementation decisions that can be discussed without exposing client-sensitive details.
- Product model
- Multi-tenant B2B2C SaaS
- Client type
- Schools & student organizations
- Timeline
- 2025 — July 2026
- My role
- Lead engineer & platform architect
- Context
- Private commercial product
- Delivery scope
- Architecture · backend · integration · operations
01
Product surfaces
Product surfaces
Distinct product surfaces made school, association and campus responsibilities visible before getting into the backend architecture.
School admin dashboard
School-scoped administration, access governance and operational oversight.
Association workspace
Association operations, payments, events and member management.
Campus identity flow
Microsoft login, campus membership reconciliation and session lifecycle.
02
Problem and constraints
Problem and constraints
Assaliz was not a generic school portal. It had to support schools, student associations and campus users inside one platform while preserving distinct responsibilities, tenant boundaries and auditability. Treating all of them as ordinary users would have made permissions, ownership and incident handling ambiguous.
Different actors, different authority
School admins, associations and campus users could not share one flat permission layer without blurring who governs what.
External identity, local authorization
Microsoft could authenticate users, but school-scoped access and revocation still had to remain platform-owned.
Shared platform, separate workflows
Payments, memberships, domains, messages and events depend on the same tenant context without being the same product surface.
Operational traceability
Administrative actions and integration-side changes had to remain inspectable in production.
03
My exact ownership
My exact ownership
I designed
- Tenant and domain boundaries across schools, campuses, associations, memberships and roles.
- The identity model separating Microsoft authentication from local authorization.
- Session, CSRF and refresh-token boundaries for browser-based access.
- Integration boundaries around directory sync, payments and operational services.
I implemented
- FastAPI backend domains and school-scoped authorization rules.
- Microsoft Entra login, Graph membership reconciliation and campus identity flows.
- Cookie-based access, refresh rotation and paired CSRF validation.
- Audit, tracing and production safety controls around requests and administrative actions.
I collaborated on
- Shared API contracts used by the admin, association and campus product surfaces.
- Product behavior alignment between audience-specific frontends and backend rules.
- Operational rollout decisions across identity, payments and tenant configuration.
03
Objectives
Objectives
Product
Give each audience a focused application while preserving one shared platform and data model.
Identity
Connect Microsoft login and directory synchronization without making the external directory the authorization database.
Transactions
Support association payment configuration and financial operations behind school-scoped governance.
Operations
Make requests, admin actions, background jobs and integration failures traceable in production.
04
System architecture
System architecture
Admin · Association · Campus · Landing
FastAPI · domain services · role boundaries
PostgreSQL · Redis · object storage
Microsoft Graph · payments · wallets
Audience-specific product surfaces stayed separate, while one shared backend and domain model enforced consistent rules and reduced duplication.
Technology stack
Product surfaces
Next.js 16 · React 19 · TypeScript · TanStack Query · Tailwind CSS
Backend
FastAPI · SQLAlchemy · Pydantic · OpenAPI
Data & runtime
PostgreSQL · Redis · Cloudflare R2 · Background workers
Integration boundaries
Microsoft Entra ID · Microsoft Graph · Stripe Connect · HelloAsso · Bridge
05
Core domain model
Core domain model
The data model makes organizational ownership explicit. Schools govern campuses, campuses connect users and associations through memberships, and financial or event operations attach to the correct institutional context instead of generic users.
School
Top-level tenant boundary, policy owner and operational scope.
Campus
Execution context for domains, membership and local identity rules.
Association
Operational entity for events, payments, activities and financial setup.
User and membership
Local account plus campus or association relationship, role and access state.
Role and permission scope
Authorization remains school-scoped even when identity comes from an external directory.
Payment account and transaction
Association financial operations remain tied to the correct governance boundary.
06
State model
State model
The identity lifecycle reconciles an external directory membership with a local campus role and an independently revocable session.
Directory detected
A Graph group member matches an approved campus domain.
Membership reconciled
The local account and campus membership are created or updated.
Session active
Access, refresh and paired CSRF cookies represent the authenticated session.
Session rotated
Refresh rotation renews access while preserving revocation control.
Alternate transitions
Directory removal
A stale SSO membership is deactivated during reconciliation.
Logout or invalid refresh
The session is revoked and a new authentication is required.
Microsoft handled authentication, but the platform kept local authorization control so revocation and school-scoped permissions remained deterministic.
07
Engineering challenges
Engineering challenges
External identity without external authorization
Microsoft owns authentication and directory membership, but product permissions must remain school-scoped, revocable and auditable locally.
Separate login, directory-sync and calendar registrations; link provider identities to local users; reconcile school memberships and persist roles in the platform database.
The platform accepts synchronization lag and must operate reconciliation jobs, but authorization remains deterministic when Microsoft is unavailable.
If the external directory becomes the authorization database, revocation, auditability and school-specific exceptions become brittle.
Four products without four platforms
Admin, association and campus users need different navigation and permissions, while duplicated contracts and UI foundations would drift.
Use separate Next.js applications in one pnpm workspace, shared UI packages and generated API types over one domain backend.
Repository coordination and cross-application testing are heavier than a single frontend, in exchange for visible audience boundaries.
If every audience shares one undifferentiated surface, responsibilities and access checks drift into brittle conditionals.
Browser sessions across tenant subdomains
Cookie authentication spans school-specific hosts and OAuth callbacks while state-changing requests must resist CSRF and token replay.
Use short-lived access cookies, revocable refresh-token records, refresh rotation, paired CSRF validation, strict CORS patterns and secure production cookie settings.
The browser client and callback configuration are more complex than bearer tokens in local storage, but token exposure is reduced.
If browser auth relies on loose token handling, cross-tenant callbacks and state-changing requests become harder to secure and revoke.
08
Failure modes & mitigations
Failure modes & mitigations
Graph sync interrupted mid-reconciliation
Membership reconciliation remains idempotent and stale SSO deactivation is applied safely instead of assuming a partial sync completed.
Invalid or expired refresh token
The session is revoked explicitly and the browser must re-authenticate instead of silently drifting into an ambiguous state.
Cross-tenant access attempt
Tenant resolution happens before protected operations and school-scoped authorization checks are enforced at the backend boundary.
Provider outage or degraded dependency
Local authorization and persisted tenant state remain deterministic even if the external provider is slow or unavailable.
Administrative action requiring auditability
Structured request IDs and audit records preserve who changed what, in which school context and through which surface.
09
Technical decisions
Technical decisions
Separate product surfaces, shared platform
Four applications keep each audience focused while sharing contracts, tooling and a central backend.
Directory sync as a lifecycle
Graph groups are paginated, filtered by approved domains and reconciled against local memberships—including safe deactivation of stale SSO accounts.
Session security at the boundary
HttpOnly access and refresh cookies reduce token exposure; a readable, paired CSRF cookie protects state-changing requests.
10
Security & operations
Security & operations
Authentication abuse controls
Progressive lockouts use a Redis store when available and expose degraded fallback status when running in memory.
Fail-closed configuration
Production startup refuses weak application or backoffice secrets instead of silently accepting defaults.
Security regression checks
Automated checks cover security headers, cookie-auth request mode and unsafe HTML rendering.
Traceability
Structured logs redact sensitive fields, attach request IDs and record school-scoped admin actions without blocking request execution.
- Graph pagination and deterministic membership reconciliation.
- Explicit session revocation and refresh-token lifecycle.
- Production audit trail for security and deployment decisions.
11
Delivered system
Delivered system
Implementation outcomes — no unverified commercial metrics.
One tenant model
Schools, campuses and associations share explicit ownership rules instead of implicit host-based behavior.
Replaceable integrations
Identity, calendar, storage, banking and payment providers sit behind configuration and service boundaries.
Observable operations
Requests, admin mutations and long-running delivery jobs have explicit operational signals and retry behavior.
Shared delivery system
Four audience-specific applications can evolve over a shared API contract and component foundation.
What I learned
“Multi-tenant systems become easier to reason about when audience boundaries are visible in both the product surfaces and the domain model.”