Zaravand Portal.

Overview

The context behind the code.

Zaravand sells Zaraamad to municipalities and runs one install per city. The portal is where the company manages those customers: who they are, which services they buy and at what price, their subscriptions, their support tickets and their income reports. It serves 56 active municipalities and several other organisations.

The problem

The problem

More than fifty separately deployed city installs, each with its own address and version, have to be managed from one place. Subscription data must stay correct when a city is offline, and each city's revenue figures have to be collected into one consistent picture.

Architecture

Architecture

FastAPI modules with explicit controllers, services and schemas over SQLAlchemy 2, Alembic and PostgreSQL. Bridge clients run health and capability checks against each city's Zaraamad install and manage subscriptions remotely; read-only SQL Server connections collect each city's income summaries.

Code share is from the original git history up to release 1.5.0; a later re-import into a fresh history credits a teammate in current blame.

My contribution

My contribution

I started the repository and built the backend from scratch: by release 1.5.0, about ten weeks later, I had written 89% of its code, with 177 tests. That covers customers and users, the service catalog and per-customer pricing, SMS one-time-password login with verification of Django-issued tokens, the ticket workflow, the bridge to city installs, and the import of every city's income reports through a tool that runs one query against all city databases. I also built several frontend screens.

Engineering challenges

Engineering challenges

Each city install can be unreachable or on a different version, so the bridge checks capabilities first, caches subscription lookups and keeps a failure in one city from affecting the others.

Engineering reflections

Engineering reflections

A central system over many independent installs has to treat every remote call as something that can fail, and make that failure visible instead of hiding it.

Technology

The tools behind the work.

• Python
• FastAPI
• SQLAlchemy
• Alembic
• PostgreSQL
• Pydantic
• SQL Server
• pytest