DEV Community: Ilya Mikhasik

Our System Series: Cerberus. Permissions and Endpoint Access

Ilya Mikhasik — Fri, 25 Sep 2026 12:10:34 +0000

After a user signs in, the system needs more than an answer to the question, “Who is this?” It also needs to answer, “What is this user allowed to do in this project?”

Cerberus is the platform’s centralized permissions service. It manages which users can access which operations in which services, and it manages groups that can be used as part of the same access model.

The User Profiles Service retrieves this information during login and includes it in the JWT. Services then use the shared authentication library to decide whether a request can reach a particular endpoint.

Permissions

A user does not simply have a generic “administrator” or “editor” label. Permissions are assigned for specific operations in specific services.

For example, a user may be allowed to manage groups in Cerberus while also being allowed to create tasks in the Quest service:

{ "Cerberus": [ "post_group_group_name_users", "delete_group_group_name_user_user_id" ], "Quest": [ "get_quests", "patch_quest_quest_id", "post_task" ] }

This expresses access in terms of the capabilities offered by each service.

Cerberus keeps a configured list of recognized services. Each service name is mapped to a UUID in the service configuration. When permissions are assigned, Cerberus verifies that the target service is part of this known set.

This prevents permission records from being created for arbitrary or misspelled service names.

Managing access

Cerberus provides endpoints for viewing and changing a user’s permissions:

GET /permissions/user/{user_id} POST /permissions/user/{user_id} DELETE /permissions/user/{user_id}

When assigning permissions, the request identifies:

The user receiving access
The project where the access applies
The target service
The operations that should be allowed

Permissions are assigned within a project. When a caller changes another user’s permissions, Cerberus verifies that the request’s Project-ID matches the project carried in the caller’s token.

Permission management is itself protected. A user must have the appropriate Cerberus permission before they can grant, change, or remove another user’s access.

The service also supports default permissions for a project. These make it possible to establish a baseline level of access and then add more specific permissions for individual users when needed.

Groups

Permissions are not always managed only person by person. Cerberus also supports groups.

A group is an entity, and membership is represented through the same link-based model used elsewhere in the system:
User ─── user_group link ─── Group

Cerberus provides operations for retrieving a user’s groups, adding users to a group, and removing users from a group.

The User Profiles Service retrieves group membership during token creation. The group information then travels with the rest of the user’s access context.

This allows services to use both direct permissions and group membership when applying access rules.

Shared authentication library

Cerberus manages permission assignments, but it does not sit in front of every request to every service.

Each service uses a shared authentication library. The library provides the validate_permissions decorator, which is applied to endpoints that need access control:

@validate_permissions("POST_PERMISSIONS_USER_USER_ID") async def set_user_permissions_in_project(...): ...

The decorator executes before the endpoint function. It reads the service’s authorization configuration, extracts and checks a token when necessary, verifies project context, and allows or rejects the request before business logic runs.

This gives services a common enforcement mechanism while allowing each service to define its own endpoint permissions.

Endpoint configuration

Each service keeps its endpoint access rules in auth.yml.

For example, Cerberus defines:
`debug_mode: PROD

permissions:
INFO: OPEN

GET_PERMISSIONS_USER_USER_ID: OPEN
POST_PERMISSIONS_USER_USER_ID: GRANTED
DELETE_PERMISSIONS_USER_USER_ID: GRANTED

GET_GROUPS_USER_USER_ID: OPEN
POST_GROUP_GROUP_NAME_USERS: GRANTED
DELETE_GROUP_GROUP_NAME_USER_USER_ID: GRANTED`

The endpoint code identifies the operation:
@validate_permissions("POST_GROUP_GROUP_NAME_USERS")

This keeps endpoint business logic separate from access policy.

Access levels

The library recognizes three access levels:

OPEN -- No token is required
AUTHORIZED -- A valid JWT is required
GRANTED -- A valid JWT containing the required permission is required

An OPEN endpoint is available to any caller.

An AUTHORIZED endpoint requires a Bearer token that can be validated with the service’s JWT public key and configured algorithm.

A GRANTED endpoint requires a valid token and the permission associated with the endpoint. The permission can be assigned directly to the user or made available through group membership.

Request validation

The shared decorator applies the following flow:

Request → validate_permissions → resolve endpoint access level from auth.yml → extract token when required → read user context from the token → compare token project with request Project-ID → validate token or required permission → execute endpoint

Development and production behavior

The configuration includes a debug mode.

In development mode, an endpoint that is absent from auth.yml is treated as open. In production mode, an endpoint without an access configuration is denied.

This makes production behavior fail closed: an endpoint must be intentionally configured before it can be exposed.

Authorization can also be disabled entirely through service configuration. In that case, the decorator becomes a no-op and returns the original function without applying access checks.

Closing perspective

Cerberus provides the centralized model for permissions and groups. The shared authentication library turns that model into endpoint protection across services.

Cerberus determines which operations a user may perform. The User Profiles Service places that resolved context into a JWT. Each service uses auth.yml to classify its endpoints as open, authenticated, or permission-restricted, and validate_permissions enforces that classification before business logic runs.

This gives the platform one permission model and one access-validation mechanism while allowing each service to define the rules appropriate to its own API.

Our System Series: JWT Tokens. Identity, Context, and Permissions

Ilya Mikhasik — Thu, 24 Sep 2026 13:39:30 +0000

Previous: Event Processing

Every request in a microservice system needs context. A service needs to know who is making the request, which project the request belongs to, which account is being used, and what the caller is allowed to do.

In our system, this context is carried by JWT access tokens.

A token is created after a successful login and then passed to the services involved in the request. It contains the user identity together with the project, account, organization, group, and permission context required for authorization.

Login is more than password verification

The User Profiles Service exposes two endpoints for obtaining an access token:

POST /auth/login POST /auth/token

Both endpoints authenticate a user with a username and password, require a Project-ID header, and can receive an Account-ID header.

POST /auth/login returns a full login response. It includes the access token together with selected user data, abbreviated profile data, organization information, permissions, and groups.

POST /auth/token returns only the access token and token type. It is intended for callers that already have the user context they need and only require a new Bearer token.

The authentication process begins by locating the active user by login and verifying the password. Before password verification, the service checks account flags that may require the user to restore or change their password.

But a successful password check is only the beginning.

The service must also determine where the user is acting in the system. The same user may have access to different projects, accounts, organizations, groups, and operations. A useful access token therefore needs to carry more than a user ID.

What the token contains

The access token is a signed JWT containing a sub object. This object represents the security context created during login.

The basic identity and context fields are:
user_id
profile_id
project_id
account_id
device_id
user_ip

Depending on the user’s relationships and assigned access, the token also contains:
permissions
groups
organizations

A simplified token payload looks like this:
{ "sub": { "user_id": "898ccff4-ba19-4a52-a3e3-4b631047e6a9", "profile_id": "898ccff4-ba19-4a52-a3e3-4b631047e6a9", "project_id": "2c03471b-7792-4f9a-aa8a-6811810959f0", "account_id": "9fe20687-4036-48ba-951d-458092012288", "permissions": { "Quest": [ "get_quests", "post_quest" ] }, "groups": [ "organization" ], "organizations": [ "f607b439-d88c-41c8-8581-5655f71722cf" ] }, "iat": 1790254220, "exp": 1790297420 }

The API response also returns selected user and profile details. For example, the caller receives user information, account flags, an abbreviated profile, and the Bearer token itself.

The token is what subsequent services use to identify the caller and evaluate access.

Building the context

The token’s project and account information is not simply copied from request headers. The User Profiles Service resolves the user’s relationships before placing that information into the token.

First, the service verifies that the user is connected to the current project through a project-user link.

It then looks for account-user links within that project. If there is one matching account, the service uses it. If several accounts are available, the caller specifies the intended account through the Account-ID header.

The service then verifies that the selected account is connected to the project through a project-account link. Finally, it retrieves the organizations to which the user belongs within that project and account.

User
→ project-user link
→ account-user link
→ project-account link
→ organization memberships
→ token context

This is where the graph-like model becomes part of authorization. The links that connect users, projects, accounts, and organizations are used to construct the context in which a user can act.

Permissions and groups

Permissions are retrieved from the permissions service and added to the JWT under the relevant service name.

For example:
{ "permissions": { "FletcherGoods": [ "post_goods", "patch_goods_goods_id", "delete_goods_goods_id", "patch_goods_goods_id_status" ], "Quest": [ "get_quests", "patch_quest_quest_id", "post_task" ] } }

The structure provides a direct mapping between a service and the operations permitted for that user.

Groups provide another part of the authorization context. A user may belong to one or more groups within a project, and those groups are included in the token alongside individual permissions.

The /auth/login endpoint can also receive a requested permission set. If it does, the service filters that request against the user’s actual permissions. The resulting token contains only permissions already assigned to that user.

Signing tokens

Tokens use RS256, an RSA signature algorithm based on SHA-256. The private key signs tokens, while services use the corresponding public key to verify them.

Toknes also contain two time-based claims:
iat — issued at
exp — expiration time

These record when a token was created and when it stops being accepted.

After a token has been issued, protected endpoints use FastAPI’s OAuth2PasswordBearer dependency to extract the Bearer token from the request. The service verifies it with the public key, reads the user ID from sub, and loads the current user record from the registry.

Invalid, expired, malformed, or userless tokens become application-specific authorization errors.

Different lifetimes for different flows

The normal access-token lifetime is controlled through configuration. The service also supports two scope-based lifetime modes:
short:
infinite:

Short tokens default to five minutes if no explicit duration is supplied. They are used for focused actions such as password restoration.

For example, a password-restore token contains a reduced security context:
{ "user_id": "<user UUID>", "project_id": "<project UUID>", "permissions": { "UserProfiles": [ "patch_auth_password_trusted" ] } }

The trusted password-change endpoint validates the token’s remaining lifetime before allowing the password update.

This gives the password-recovery flow a token with a specific purpose and a short usable period, rather than requiring the full set of permissions carried by a normal access token.

Closing perspective

JWTs connect authentication to the rest of the system.

A password verifies the user’s identity at login. The user’s links to projects, accounts, and organizations establish the context in which that identity is operating. Groups and permissions determine which operations are allowed. The resulting JWT carries that context to the services handling later requests.

In the next article, I will describe Cerberus, the permissions service. I will look more closely at how authentication, authorization, and permission checks are applied by services after a token has been issued.

Next: Permissions and Endpoint Access

Our System Series: Event Processing. From Business Events to External Actions

Ilya Mikhasik — Wed, 23 Sep 2026 13:59:37 +0000

Previous: Sensitive Data Encryption

The Signup Service creates the user and profile records, and the User Profiles Service encrypts protected data before it is stored. There is still one task left after successful registration: notifying the user.

That work is handled by the Event Processor.

The Event Processor provides a controlled way for services to publish events, route those events through configurable handlers, and deliver the resulting messages through external channels such as email, REST APIs and messengers.

The signup email is one example. The same mechanism can support many kinds of follow-up work without placing that work directly inside the service that created the original event.

Why use an Event Processor?

A business workflow should not need to perform every follow-up operation synchronously.

After a user signs up, the Signup Service needs to return the new user and profile identifiers. It should not also need to know how to select an email template, configure an email provider, send the email, handle delivery failure, or retry a temporary error.

Instead, it publishes a signup event.

The service that produces an event and the service that consumes it remain independent. Kafka topics provide the boundary between them: producers publish events to a topic, while consumers subscribe to and process events from that topic. Kafka documentation describes producers and consumers as decoupled, with events organized and durably stored in topics.

Event ingress
The Event API receives events through:
POST /event/send/{event_topic}

The endpoint validates the caller’s permissions, verifies that the requested topic is allowed, adds service-level context, and publishes the event to Kafka.

Each event message contains:
event_id
project_id
data
token, when provided

The Event API generates a UUID event_id for every incoming event. This provides a stable identifier that can be used to trace the event through processing stages and logs.

The project_id identifies the project context. When the caller supplies an authorization token, the Event API includes it in the Kafka message so downstream actions can use the required authorization context.

The API prevents callers from publishing directly to internal service topics. It also verifies that the requested Kafka topic exists. If the requested topic is missing from the cached topic list, the service refreshes the list before returning a not-found error.

Shared Kafka producer

The Event API creates one shared AIOKafkaProducer during the FastAPI application lifespan.

At startup, the service:

Initializes its shared HTT P client
Initializes logging and authorization
Loads the available Kafka topics
Creates and starts a Kafka producer using the configured security settings

FastAPI lifespan handlers are designed for logic that runs before the application begins serving requests and during shutdown, which makes them suitable for managing shared resources such as external clients and message producers. AIOKafkaProducer.send_and_wait() publishes a record and waits for the send operation to complete.

Using one producer for the application avoids creating and stopping a separate Kafka producer for every incoming event.

EVENT, PREPARE, and PUSH

The intended processing model has three phases:

EVENT → PREPARE → PUSH

EVENT

The Event API receives an event from another service, validates it, enriches it with event and project context, and publishes it to Kafka.

The Event API does not need to know whether the event will lead to an email, an external REST call, a messenger notification, or another action. It only accepts and publishes the event.

PREPARE

Some events need transformation before they can be delivered. An email must be rendered from a template, a REST endpoint may require a particular JSON structure, and a messenger text may require its own formatting.

A configured processor consumes an event from one topic, runs one or more preparation actions, and publishes the resulting delivery packages to the next topic.

For example:
{ "topic": "accrual-send", "actions": [ { "module": "prepare_json", "next_topic": "RestAPI" } ], "description": "awarding points", "object_type": "event.processor" }

In this example, the processor receives an event from the accrual-send topic, invokes the prepare_json module, and sends the prepared result to the RestAPI topic.

PUSH

The PUSH phase delivers the prepared package to an external destination.

A transport action can use protocols such as:

SMTP
REST
Messenger
Other transports added later

For example:
{ "topic": "accruals", "actions": [ { "module": "restapi_send", "next_topic": "accrual-send", "template_name": "accrual" } ], "descriptions": "retrieving user points for payment processing", "object_type": "event.transport" }

This handler consumes messages from the configured topic, invokes the restapi_send module, and can use the configured accrual template when preparing the destination request.

The Event Processor keeps its own internal headers separate from headers required by an external destination. This matters because a third-party REST API may require its own authorization or protocol-specific headers that should not be confused with service-to-service context.

Configurable handlers and actions

The Event Processor is configuration-driven.

Its configuration API manages:

Event-handler configurations
Email-sender configurations
Message templates
Access-token configurations

These records are stored in the configuration registry. They are loaded as active records and can be scoped by project.

Configurations allow routes, actions, templates, delivery settings, and access details to be managed outside the core event-ingress endpoint.

For example, templates can be loaded by project and template name. Email configuration can be retrieved separately from event-handler configuration. Access configuration can be stored per project rather than embedded in service code.

Handler lifecycle

At startup, the service loads active configurations from the configuration registry.

The current handler configuration types include:
event.processor
event.transport
event.handler

Each configuration creates an event handler with:

A Kafka topic to consume
A handler type
A Kafka consumer for that topic
Access to the application-level producer
A list of actions loaded from configuration
A directory containing action modules

Each action identifies a module that implements its logic and a next_topic for the action result.

When a handler consumes an event, it runs the configured actions asynchronously. Action tasks are named with the event ID, handler topic, and action name, making concurrent work easier to trace during logging and debugging.

Actions that return a result publish a new event to their configured downstream topic, where another handler can continue processing.

Incoming event → consume from topic → run configured actions → collect results → publish results to next topics

This allows processing to be expressed as a pipeline of independently configured stages rather than as one large synchronous workflow.

Configuration loading

Configuration records are loaded from the configuration registry through asynchronous HTTP requests.

The loaders select only active records. They filter by object_type and optionally by project_id. This allows multiple projects to use the same Event Processor while maintaining separate handler configurations, templates, email settings, and access configurations.

The current API supports creating and updating event configurations. A planned improvement is to notify the event-handler container when a configuration changes so the relevant handler can start or restart without a full service restart.

Failure handling

The intended model treats delivery outcomes as events.

After a PUSH operation, the system can produce outcomes such as:
_success
_fail

A more flexible configuration can specify which event should be emitted after successful or failed delivery.

Failure behavior can also depend on an external response, such as an HTTP status code or an application-specific error code like USER_NOT_FOUND.

Potential configured responses include:
RETRY
STOP

A retry policy can specify a delay before another delivery attempt. A stop policy ends processing for that delivery.

These capabilities describe the intended direction of the Event Processor. They should be understood as planned behavior until the associated retry, result-event, and failure-routing logic is implemented and verified.

Signup email example

The signup workflow ends by sending an event after user and profile creation succeeds.

The Signup Service does not send the email directly. It publishes an event containing the information required by the configured event-processing pipeline.

The Event Processor can then:

Receive the event through the Event API
Publish it to Kafka
Consume it through a configured handler
Prepare an email package using an action and template
Send the email through a configured delivery mechanism
Optionally publish a success or failure event

The registration workflow can complete independently of delivery, while notification behavior remains configurable.

Closing perspective

The Event Processor is built around a simple principle: applications publish facts about what happened, while configurable handlers decide what should happen next.

The Event API controls event ingress. Kafka carries events between stages. The configuration registry stores handler rules, templates, delivery settings, and access details. Action modules prepare or deliver messages.

The architecture is still evolving. The shared application-level Kafka producer is already in place, while dynamic handler reloads, configurable retries, and success or failure events are planned improvements.

In the next article, I will discuss the service-to-service security model: tokens, authentication, authorization, and permissions.

Next: JWT Tokens

Our System Series: Sensitive Data Encryption

Ilya Mikhasik — Tue, 22 Sep 2026 13:24:21 +0000

Previous: Registries

The registry layer gives us a consistent way to store and retrieve users, profiles, links, and other entities. The next question is how to protect sensitive values before those entities reach the database.

The answer in this system is to encrypt selected fields in the User Profiles Service. As shown in the signup workflow, this service sits between the Signup Service and User Profiles Registries. It prepares user and profile data before it is persisted, including encryption of protected values.

The registry receives encrypted values and stores them through its normal interface. It does not need to understand which fields are sensitive or implement encryption rules itself.

Encrypting at the registry boundary

The encryption module is implemented as decorators around the shared registry-interaction function:
@encrypt_payload @decrypt_payload async def interact_with_registry(...): ...

Before a POST, PUT, or PATCH request is sent, the encryption decorator examines the target registry and encrypts the relevant fields. After a GET request completes, the decryption decorator reverses that transformation before the result is returned to the User Profiles Service.

The registry name determines which rules apply.

The same distinction is applied when decrypting individual user and profile records, as well as collection responses from users and profiles registries.

This approach keeps encryption close to the service that understands the meaning of the data. It also prevents encryption and decryption calls from being copied into every method that interacts with user or profile records.

What is encrypted

The system uses field-level encryption rather than encrypting the complete record. Some profile data is nested. For nested profile data, the module encrypts the values inside media, email, and phone entries while preserving the surrounding JSON structure.

The record’s overall structure remains available. A profile can still be identified, associated with a project, checked for status, and connected to other entities. What is protected are the values that reveal personal information.

The encryption format

The module uses AESSIV from the Python cryptography package and creates a 512-bit encryption key.

Before encryption, a value is serialized as JSON. This allows the same function to work with strings and structured values. The ciphertext is then encoded with URL-safe Base64 before it is stored in a registry record. That makes the encrypted result safe to place inside JSON payloads and send through the registry API.

AES-SIV is an authenticated-encryption construction. In this implementation, no nonce is supplied, so the encryption is deterministic: encrypting the same normalized value with the same key produces the same ciphertext. The cryptography documentation describes this usage as deterministic authenticated encryption.

That property is useful because it allows the system to search protected values by encrypting the search term first. The trade-off is that identical plaintext values produce identical ciphertext values, revealing equality between stored values.

Tracking key versions

When the module encrypts at least one field, it records the active key version in the object metadata.

When a record is returned from the registry, the module checks this value before attempting decryption.

A record with the current key version is decrypted.
A record without a key_version is returned unchanged.
A record marked with another key version is not decrypted with the current key.

This supports a transition in which legacy plaintext records and newly encrypted records can coexist. It also gives every encrypted record the information needed for a future key-rotation process.

At present, the module decrypts records only when their version matches the key configured in the service. A full rotation design would later need to support reading older versions, re-encrypting records in batches, and retiring older keys after the migration is complete.

Searching protected profile data

Encryption changes how the system searches user and profile records.

A normal database query cannot compare a plaintext value such as Ivan with an encrypted value stored in the profile record. To handle this, profile search is performed twice.

First, the service searches legacy records using plaintext filters. Then it normalizes and encrypts the same values and performs a second search for encrypted records.

For example, a name is normalized before encryption and the resulting ciphertext is then used in an exact registry lookup.

Phone numbers are normalized and validated before encryption. Email addresses are converted to lowercase first. This is necessary because deterministic encryption only produces matching ciphertext when the input is identical.

The two result sets are merged by profile_id, so the same profile is not returned twice.

This allows plaintext and encrypted records to coexist while encryption is introduced gradually rather than requiring every historical record to be migrated at once.

What the design preserves

The purpose of the module is not only to encrypt data. It must also preserve the behavior needed by the application.

The design allows the system to:

Encrypt selected personal and authentication-related fields before storage
Keep encryption rules in one shared module
Continue using the same registry APIs
Read legacy unencrypted records during the transition
Find encrypted records through normalized exact-match searches
Identify which key version was used for a record

There is an important limitation: deterministic encryption allows equality matching, but not partial matching. Searches such as “starts with,” “contains,” or fuzzy text matching cannot operate directly on the encrypted values. The encrypted search path therefore uses exact comparisons.

Closing perspective

The User Profiles Service applies encryption at the point where sensitive user and profile data enters or leaves the registry layer. This keeps protected values out of plaintext database storage while allowing the registry architecture to remain standardized and reusable.

The next step for this design is a formal key-rotation workflow: support multiple key versions for decryption, re-encrypt records in controlled batches, verify that the migration succeeded, and retire the old key only after the process is complete. These tasks are in the development pipeline.

In the next article, I will describe the Event Processor. During user signup, the Signup Service sends an event after user and profile creation is complete. The Event Processor receives that event and handles follow-up work, including sending the signup email to the new user.

Next: Event Processing

Our System Series: Registries. From the Network Discovery Service to Reusable Registries

Ilya Mikhasik — Mon, 21 Sep 2026 13:00:00 +0000

Previous: User Signup Service

In the previous article, I described user signup as an example of how our services interact. This article looks at the registry layer in more detail: where the idea came from, what a registry represents, and how application services communicate with one.

The Network Discovery Service

The idea of registries originated in an application I will call the Network Discovery Service, internally named Kroozheva.

The application was designed to represent networks of connected objects. Users could create objects such as people, workplaces, cities, and professions, then connect them to one another. These relationships could be used to discover new contacts through existing connections.

For example, a user could create themselves as a node, add family members, friends, workplaces, and cities, and connect these objects. They could then search the network for someone with a particular profession who was connected through a friend or another trusted path.

This requirement influenced the database design from the beginning.

A model based on fixed entity types would require separate tables for people, places, professions, and every other object type. Relationships would require additional intermediate tables, and the number of tables would grow as new entity types were introduced.

Instead, we designed a generic model based on entities and links:
Entity ─── Link ─── Entity

An entity contains common fields such as its identifier, type, dates, status, and flexible JSON data. A link represents a relationship between two entities and contains the connected identifiers, direction, type, weight, and any relationship-specific data.

This gave us a flexible data model for representing networks without creating a new relationship structure for every combination of entity types.

From the data model to registries

Once the generic entity model had been defined, we needed a consistent way to access the stored objects.

Every new entity type required the same basic operations:

Create records
Retrieve individual records
Search and list records
Update records
Delete or deactivate records
Perform batch operations where necessary

Writing these operations repeatedly for every entity would have produced a large amount of nearly identical code. It would also have made behavior inconsistent between services.

This led to the idea of registries: database-access services with a standard CRUD interface for a particular registry or table.

A registry could represent a conventional entity, such as users or profiles, or a relationship structure such as links. The application layer could then use the same style of interface regardless of which registry it needed to access.

Registry API

A typical registry exposes separate endpoints for individual and collection operations. The attached Swagger UI shows this pattern using good, goods, and link registries.

This convention makes registry APIs predictable. A service that already knows how to interact with one registry can use the same general approach with another.

Querying registry collections

A registry is more useful than a basic CRUD interface because its collection endpoints support structured queries.

A request can limit the number of returned records and specify the starting position:
GET /api/objects/?limit=10 GET /api/objects/?limit=10&offset=5

The first request returns ten records. The second starts at offset five and returns the next page.

The API also supports filtering by standard fields:
`GET /api/objects/?object_type=person
GET /api/objects/?project_id=3fa85f64-5717-4562-b3fc-2c963f66afa6
GET /api/objects/?account_id=3fa85f64-5717-4562-b3fc-2c963f66afa6
GET /api/objects/?created_date__gt=2023-06-15'

Several filters can be combined:
'GET /api/objects/?limit=10&offset=5&object_type=person&name=Ivan'

This returns one page of objects matching both the object type and name.

The same query conventions can be used across different registries, so application services do not need a separate querying approach for every entity type.

Querying flexible data

The generic model includes a JSON data field for entity-specific attributes. The registry API supports filtering inside this field without requiring every possible attribute to become a database column.

Examples include:
GET /api/objects/?data=username__exact=Ivan GET /api/objects/?data=number__gte=18::int GET /api/objects/?data=number__lt=12.5::float
The query identifies the JSON key, the lookup operation, and, when necessary, the expected value type.

Supported lookups include:
icontains
exact
iexact
gt
gte
lt
lte
endswith
iendswith
startswith
istartswith

Several JSON-field filters can be combined:
GET /api/objects/?data=username__icontains=a&data=some_id__exact=23

This capability is important for the generic registry model. Entity-specific information can be stored and queried while the registry retains a common structure.

Searching and ordering

The API also supports general search.

Without a field restriction, the search value is applied across all searchable fields:
GET /api/objects/?search=2

A search can be limited to one field:
GET /api/objects/?search=2&field=object_code

It can also target several fields:
GET /api/objects/?search=350&field=object_code&field=project_id&field=data

Nested JSON fields can be addressed with double-underscore notation:
GET /api/objects/?search=+78564523636&field=data__telephone

Results can be ordered explicitly:
GET /api/objects/?ordering=object_code GET /api/objects/?ordering=-object_code

Multiple ordering fields are supported:
GET /api/objects/?ordering=object_code,created_date

Ordering can also use values inside the JSON data field:
GET /api/objects/?ordering=data__number,-data__date

The default ordering is meta__internal_id in descending order, so newer objects appear first unless another ordering is requested.

Pagination, filtering, searching, and ordering make the registry API useful for both ordinary application requests and larger data-processing operations.

The registry interaction module

Application services do not construct registry requests independently. We use a shared module that centralizes communication with registry services.

Its main entry point is:
async def interact_with_registry(...)

The function receives:

The incoming FastAPI request
The HTTP method
The registry base URL
The registry name
An optional object ID
Query parameters
Request data
Filtering and error-handling options
A request timeout

It constructs the registry URL from the supplied registry name and optional ID, serializes request data, forwards the session context, performs the HTTP request, validates the response, and converts registry failures into application-specific exceptions.

This keeps registry interaction consistent across application services.

Request construction

The module supports the standard HTTP methods:
GET
POST
PUT
PATCH
DELETE

When an object ID is not supplied, the module builds a collection URL:
{registry_url}/{registry_name}/

When an ID is supplied, it builds an individual-object URL:
'{registry_url}/{registry_name}/{id}/'

Request bodies are serialized with FastAPI’s jsonable_encoder, which allows schema objects and values such as UUIDs and datetimes to be converted into JSON-compatible data before being sent to the registry.

Timeouts and failures

The module obtains the HTTP client from the FastAPI application and applies a configurable timeout to every request.

Transport-level failures are logged and converted into RegistryInteractionException. This gives application services a consistent error type instead of exposing the underlying HTTP client’s exception classes.

The response body is parsed as JSON. If parsing fails, the module raises IncorrectFormatInRegistryException

The module also handles several registry-level conditions:

A 404 response or empty response can become NotFoundException
A duplicate-object response containing exists becomes EntityExistsException
A hidden or deactivated object can become RegistryObjectDeactivatedException
Other unsuccessful responses become RegistryInteractionException

The active_records and raise_not_found parameters allow a caller to adjust this behavior for a particular operation.

The shared module therefore acts as an integration boundary. Registry-specific HTTP behavior is handled in one place, while application services work with consistent application-level exceptions.

Creating a registry

The Registry Factory was created to reduce the repetitive work involved in introducing new registries.

A developer creates a registry by running a Django management command:
python manage.py createregistry --template=registry_template.zip people --model_name=Person

The command receives:

The template to use
The registry name, such as people
The model name, such as Person

The factory generates the application structure for the new registry.

The generated registry is then added to INSTALLED_APPS:
INSTALLED_APPS = [ "registry_config", "links", "rest_framework", "django_filters", "people", ]

The developer creates and applies database migrations:
python manage.py makemigrations python manage.py migrate

The generated viewsets are then registered with the project router:
router.register(r"people", PeopleViewset) router.register(r"person", PersonViewset)

This exposes collection and individual-object endpoints using the same convention as existing registries.

Testing and documentation

The registry can be tested independently:
python manage.py test people

A coverage report can be generated with:
coverage run manage.py test people

The service can then be started locally:
python manage.py runserver

Its API can be inspected through Swagger UI.

The project wiki documents this workflow, including registry creation, project integration, migrations, testing, and API access.

The documentation serves two audiences:

Developers creating a new registry
Developers integrating with an existing registry

This distinction is important. Someone using a registry should be able to understand its API without studying the factory’s implementation. The generated service should be predictable, and its documentation should make its behavior discoverable.

From command to working API

The complete workflow is:
Run the factory command
→ add the generated registry to the project
→ create and apply migrations
→ register the viewsets
→ run tests
→ inspect the API in Swagger UI

This is what turns the Registry Factory from a code-generation script into a practical development tool. It does not merely create files; it defines a repeatable path from a new entity name to a tested, documented, database-backed API.

The factory provides the common structure. Developers can then add entity-specific fields, validation, permissions, and business rules where necessary.

Generic persistence and business logic

Registries are intentionally generic. They manage records and expose persistence operations, but they do not own the complete business meaning of a workflow.

The Registry Factory defines the common structure of a registry and its entities. Developers are not expected to redesign that structure for every new registry. The purpose of the factory is to ensure that registries follow the same data model, API conventions, metadata structure, filtering behavior, and CRUD interface.

This standardization allows application services to work with different registries through the same interaction patterns.

In the next article, I will describe how our system encrypts protected data before storing it in the database. I will explain where encryption takes place in the service architecture, how encrypted data is passed to the registry layer, and how the design separates data protection from generic persistence operations.

Next: Sensitive Data Encryption

Our System Series: User Signup. Creating Users, Profiles, and Relationships

Ilya Mikhasik — Fri, 18 Sep 2026 12:09:31 +0000

Previous: Architecture Overview

In the previous article, I introduced the four-tier architecture used by our system and described its graph-like data model. This article shows how those ideas come together in a practical business workflow: user registration.

User registration is not limited to creating a single database record. The workflow creates a user, associates that user with a project and an account, creates a profile, associates the profile with the project, and triggers a signup email.

The Signup Service coordinates the workflow, while the User Profiles Service and User Profiles Registries handle user-related data operations.

The complete interaction is shown in the accompanying diagrams:

User signup, part 1.
User signup, part 2.

Separating users and profiles

The system separates user and profile entries because they contain different categories of information.

A user entry contains system identity and authentication-related information. It includes the user ID, user type, registration date, login, last-login timestamp, account-status flags, and the profile_id of the associated profile.

A profile entry contains personal and project-related information. It includes the profile ID, profile type, first and last names, birth date, sex, contact phone numbers, contact email addresses, main photo, project ID, and additional information such as education, specialty, registration address, and personal-data consent.

The user entry references the profile through profile_id. In the usual case, user_id and profile_id have the same value. This makes it easy to correlate the two records while keeping their responsibilities separate.

This separation establishes a clear boundary between:

Authentication and system identity.
Personal and user-facing information.
Account and project relationships.
Access control and profile management.

Authentication-related operations can work with the user entry without loading the full profile. Profile-related operations can work with personal data without exposing authentication-specific fields such as login status or password-management flags.

The user and profile are separate registry entries, but the profile_id field provides their direct association. Other relationships, such as the user’s association with an account or project, are represented through link records.

Registration flow

The registration process is divided into two stages:

Creating the user and establishing the user’s relationships.
Creating the profile and triggering the signup email.

The client sends the registration request to the Signup Service. The request contains user and profile data, together with Project-ID and Account-ID headers that provide the context for the new registration.

The Signup Service coordinates the process but does not directly access the database. It delegates user and profile operations to the User Profiles Service.

Creating the user

The User Profiles Service receives the request to create a user and encrypts the relevant data before persistence.

It then asks User Profiles Registries to create a user entry. The registry service inserts the record into the users table and returns the result.

The user entry contains system and authentication-related data, including:

User ID
User type
Registration date
Login
Last-login timestamp
Account-status flags
Associated profile ID

After the user entry has been created, the User Profiles Service creates two relationships:

A project-user link
An account-user link

These links associate the new user with the project and account identified by the request headers.

The relationships are stored as link records rather than as separate relationship tables. This is an example of the graph-like data model introduced in the architecture overview.

Creating the profile

After the user has been created successfully, the Signup Service asks the User Profiles Service to create the profile.

The User Profiles Service encrypts the relevant profile data and requests a profile entry from User Profiles Registries. The registry service stores the entry in the profiles table.

The profile entry contains personal and project-related data, including:

Profile ID and profile type
First name and last name
Birth date and sex
Contact phone numbers
Contact email addresses
Main profile photo
Additional information such as education, specialty, registration address, and personal-data consent

The profile receives the identifier referenced by the user’s profile_id. In the usual case, the user ID and profile ID are the same UUID, which provides a simple one-to-one association between the two records.

The User Profiles Service then creates a project-profile link, associating the profile with the project supplied during registration.

At this point, the database contains:

A user entry containing system and authentication information
A profile entry containing personal information
An account-user link
A project-user link
A project-profile link

After these operations succeed, the Signup Service returns the user ID and profile ID to the client.

Signup email event

Once the user and profile records have been created, the Signup Service sends a signup email event to the Event Processor.

The Event Processor processes the event and sends the signup email to the user.

Separating email delivery from the registration workflow keeps the Signup Service focused on creating the required entities and relationships. Email processing can be handled independently by the Event Processor rather than being implemented as part of the main registration logic.

This separation also creates the possibility of handling email-specific concerns independently, such as retries, provider integration, and delivery monitoring. The exact behavior depends on the event-processing implementation.

Design considerations

This workflow illustrates several architectural decisions:

User identity and personal profile data are stored separately
The user entry references its profile through profile_id
The same UUID is usually used for both the user and profile identifiers
Account and project relationships are represented as reusable link records
Application services coordinate business workflows
Registry services provide generic database operations
Protected data is encrypted before persistence
Email delivery is delegated to a separate event-processing component

The goal is to keep responsibilities explicit. The Signup Service does not need to know how every table is implemented, and the registry service does not need to understand the complete business meaning of registration. Each component performs a focused part of the overall workflow.

Closing perspective

User signup demonstrates how the system’s architecture and data model work together in a real business scenario.

A single registration creates several related records, but the process remains organized because each service has a defined responsibility. The Signup Service coordinates the workflow, the User Profiles Service manages user-related operations, the registry layer handles reusable persistence, and the Event Processor handles post-registration communication.

The separation between users and profiles is particularly important. Authentication and system identity are kept in the user registry, while personal and project-related information is kept in the profile registry. The profile_id field connects the two records, and the shared identifier convention makes the relationship straightforward to resolve.

The next article will focus on registries: what they are, why they were introduced, and how the Registry Factory reduces the amount of repetitive CRUD code required when adding new entity types.

Next: Registries

Our System Series: Architecture Overview

Ilya Mikhasik — Fri, 18 Sep 2026 11:53:44 +0000

Previous: Introduction to Our System Series

Our system uses a four-tier microservices architecture:
Frontend → Application Services → Registry Services → Database

Each tier has a specific responsibility. The frontend handles user interaction, application services implement business and supporting workflows, registry services provide reusable database operations, and the database stores entities and their relationships.

The system uses a graph-like data model consisting of entities and links. Entities can represent users, projects, accounts, or virtually any other type of object required by the application. Links represent relationships between entities.

Instead of creating a separate relationship table for every possible pair of entities, the system uses a general links structure. A link contains the identifiers of the connected entities, its direction, type, weight, and any additional information stored as JSON.

This approach allows us to introduce new entity types and relationships without redesigning the entire database schema. It also provides a flexible foundation for representing complex networks of connected objects.

In the following articles, I will explain the responsibilities of the application and registry services in more detail. I will use the Signup Service as an example to show how the different tiers interact during a typical business workflow.

Next: User Signup

Introduction to Our System Series

Ilya Mikhasik — Fri, 18 Sep 2026 11:50:40 +0000

Over the past few years, I have worked on several backend systems involving microservices, databases, APIs, data protection, service integration. I have often used these technologies as part of my daily work, but using a technology and being able to explain its role clearly are not the same thing.

I am writing this series to take a more structured look at the systems I have been developing and the technologies behind them. Rather than creating a simple list of frameworks and tools, I want to describe how they work together in a real application and why particular design decisions were made.

The series will begin with the architecture itself. I will explain how the system is divided into frontend, application, registry, and database layers, and how responsibilities are distributed between them. I will also discuss the graph-like data model used to represent entities and their relationships, as well as the Registry Factory I developed to automate the creation of CRUD services.

After that, I will describe several typical business scenarios. Each scenario will be supported by service diagrams showing how requests move through the system. I will explain what each service does, how the services communicate, how data is stored, and what happens when a workflow succeeds or fails.

This is also a way for me to take stock of my own experience. Writing about a system forces me to move beyond naming technologies and explain how I used them to solve concrete engineering problems. It helps identify what I understand well, what I need to investigate further, and which parts of my experience are most relevant to future projects.

The articles are not intended to present the architecture as universally correct. Every system reflects its requirements, constraints, and history. My goal is instead to describe the design honestly, explain the decisions in their original context, and reflect on what worked, what was difficult, and what could be improved.

I will begin with an overview of the architecture and then use user registration as the first example of how the different parts of the system work together.

Next: Architecture Overview