DEV Community: Mazen Aly

Part 2: Designing the Database Schema and Data Representation

Mazen Aly — Mon, 17 Aug 2026 12:51:47 +0000

Main Entities

While designing the database through an ERD, I found that the main entities are users, boards (that represent projects), columns (that represent stages) and tasks.

I designed the system's data model to be user-owned data, so every user is admin of the boards that are created by them, and there is no admin role that give full control on all the data.

Database Relational Schema

Roles

I decided to have four roles: Owner, Manager, Assignee and Viewer:

Owner: is given automatically to the user that created the board/project, allowing them to perform project-level CRUD operations in addition to CRUD operations against the columns.
Manager: allows performing task-level CRUD operations.
Assignee: can only change the status of a task (by transferring it from a column to another)
Viewer: can not take any action, can only view the board details (giving the access to the project data).

We need another table to store the role of each user per board/project, so user_board_role table is the only place where the permissions/roles are saved.

So, totally we need 5 tables: users, boards, columns, tasks and user_board_role

Also we need a table to store the events that happens, but this will be added when we setup the event-driven architecture for the system.

Handling the Order of Tasks in a Column

In the tasks table we need to preserve the order of the tasks, so when retrieving the tasks for a specific column, we need to sort them by their order.

Possible Inefficient Solution

A naive solution for this is to have a column inside the tasks table that stores a number representing the order of the task (index of the task).
However, this solution is inefficient as when we need to change the order of a specific task, we need to update all the tasks between its old position and new position and increase the number that represents their order by 1.

The time complexity of this algorithm is O(n), as for each task we need to change we have to loop over all the tasks between its new and old positions and update them.

The Chosen Efficient Solution

The more efficient approach is to store the order as a decimal (fractional index). So when we need to change the position of a specific task, all we need is to find a decimal between the index of the previous and next task to be the new index of the transferred task. We sort the tasks according to their index to get a sorted list of tasks.

For example, task A has index 1, task B has index 2, dropping a new task between them requires calculating a new index for the new task that is 1.5.

Its time complexity is only O(1), so it is very efficient. However, after many operations we may face precision problems, the solution is to rebalance when two adjacent indices get too close in value to fit a new decimal between them. Rebalancing is just looping over the tasks and assigning them integer-valued indices.

Part 1: Determining What to Build

Mazen Aly — Sun, 16 Aug 2026 17:03:35 +0000

Introduction

This is the first post of a series that documents the whole journey of my third major production-grade project. It is going to contain the whole process from an idea in my mind to a fully deployed web application.

Determining What I'm Going to Build

I wanted to tackle a new challenge centered around real-time systems and complex state management. I also wanted to explore caching strategies and other infrastructure concerns like event-driven architecture.

The First Choice, and Why I Passed on It

My first idea was a live collaborative text editor as a real-time application. But after researching the problem space, I realized that its core engineering challenges (like document synchronization, cursor synchronization, and conflict resolution) are highly specialized problems that are not closely aligned with the areas I want to grow in: backend engineering, system design, and architectural decision-making.

More importantly, these problems are already solved by mature libraries such as Yjs, paired with editor frameworks like Lexical or Monaco. In a real-world project, integrating these libraries is the right engineering decision rather than spending significant time reimplementing this highly specialized logic, which offers limited learning beyond that narrow domain.
As a result, the project's primary distinguishing feature, that is live collaborative editing, is provided by third-party software.

The Second Choice, and Why It Was The Right Fit

After some searching, I found that a collaborative project management platform is a good choice. It naturally introduces a wide range of engineering challenges that add real value to the system. Unlike a collaborative text editor, these challenges arise from the domain itself rather than being artificially introduced to justify additional technologies. They include caching, event-driven workflows, notifications, background processing, authorization, audit logging, search, and real-time synchronization, all working together to support the final product. These are exactly the kinds of problems encountered in production backend systems, providing far more opportunities to practice system design and architectural decision-making.

In the end, my goal wasn't simply to build a real-time application. It was to build a system whose domain inherently demands diverse architectural decisions and production-grade engineering challenges, allowing me to learn far more than a project centered around a single specialized problem.

Choosing the Web Framework

Why not ASP.NET

I had already built two projects using ASP.NET Core and the .NET ecosystem, so I wanted this project to expose me to a different ecosystem.

I chose Python because it is widely used beyond web development in areas such as automation, AI, and data engineering. Rather than building another project with tools I already knew well, I wanted this project to broaden my technical perspective.

Why FastAPI

It's a modern, asynchronous web framework with first-class WebSocket support, making it a natural fit for building real-time applications. Unlike Django and Flask, which require additional libraries or extensions to build WebSocket-based applications, FastAPI provides this capability out of the box.

Furthermore, it has a significantly lighter configuration model than ASP.NET Core, allowing me to move from project setup and infrastructure configuration to implementing application logic much more quickly. This provides a streamlined development experience with minimal boilerplate, enabling me to focus more on the engineering challenges of the project rather than framework configuration. It also provides many capabilities out of the box, including dependency injection, automatic request validation, and OpenAPI documentation with very little configuration in addition to being a high-performance web framework.

What's Next

In the next post, I'll dive into the details of the project, some capabilities of the system and database design.

LINTelligent — AI-Integrated service for code linting and reviewing with MCP server

Mazen Aly — Mon, 20 Jul 2026 07:17:07 +0000

Introduction

This is a post I need to share with you my thought process, decisions that I took in designing the service, and share new things that I learned. I hope anyone can benefit from my words or inspire anyone with my ideas and what I learned so we both can grow.

GitHub Repository:

mazenaly256 / LINTelligent

AI-integrated backend service for code linting (i.e. analyzing code for issues), with an accompanying MCP server for AI-agent integration.

LINTelligent

AI-integrated backend service for code linting (i.e. analyzing code for issues), with an accompanying MCP server for AI-agent integration.

Overview

A code snippet is submitted in a linting/reviewing request, either as a direct snippet in the request body or via a public GitHub file URL.

Once the linting request reaches the system, LINTelligent saves its details in the database and enqueues a background job to the job queue for handling this request, then immediately returns 202 Accepted. If a GitHub URL was provided, the code is first fetched, then the review job runs, otherwise the review job runs directly on the submitted code snippet.

After that, a worker picks up the job from the job queue and processes it, it fetches the code from the GitHub URL (if exists) then it calls the configured LLM provider with the request details and receive the review report of issues, then updates…

View on GitHub

Fun Fact: While I was testing it and request reviews on some code snippets from my previous project (Cinema Seat Reservation System), LINTelligent helped me discover a critical bug related to resource wasting as I did not dispose some objects that results in memory leak.

Overview

LINTelligent is a service that takes a code snippet as an input, and analyze it and return the issues in this code snippet.

User can either use it directly by requesting the API endpoints, or via an AI agent through the MCP server.

The workflow

User sends a review request, the service stores a new review with the code snippet in the database with status 'Pending', then it stores in the queue the methods that should be called to process this job/request with the related arguments for this request, then the service immediately returns 202 Accepted HTTP response so the client do not wait too much, detaching the client from long-running background processing.
As the jobs are saved in the queue, a worker thread picks up a job of a review request from the queue and process it, calling the methods that are stored in database as the processing way for this job. The worker sends the review request with the system prompt and the code snippet (user message) to the LLM and receives the response, then the service persists the review report that LLM returned into the database, then it notifies the user that the the request processing has been finished.

System Architecture and Design

Lets start with a basic system architecture diagram with the data flow for the service.

Asynchronous Processing

I designed this system to handle the requests in an asynchronous way, so the requests are processed in the background and then the user gets notified on completion via webhook. To achieve this I used message/job queue pattern, as shown in the diagram, the service stores the review request as a job in the job queue, and then a worker execute that job by calling the LLM, getting the review report then notify the user via webhook.

Queue Pattern

The queue pattern is simply a pattern where a producer puts messages/jobs in a queue, and then a consumer/worker (that can be either on another machine or just another thread) that reads that job/message and executes some logic to process them.

In our case, the producer is obviously the service. Inside the endpoint of requesting a new review, it stores a job in a queue.

Now we need a queue that persists the jobs/messages so the workers can take and process them one by one. Also, we need the workers themselves.

Hangfire Decision

Hangfire is a technology that provides the queue and persist the jobs data in a database (stores the details about the method that is required to be called to process some logic).

Also Hangfire reserves a number of threads form the thread pool of the application to create the workers pool, these are threads that only execute the enqueued jobs, each worker polls for jobs from the database and when there is a job it directly execute it.

Because of that, I favored using Hangfire to implement this pattern. It is simpler and provide all-in-one solution for me and at my scale I believe that it is more than sufficient.

Other choices would be more complicated and will not pay off at my scale. I could implement this using a separate queue on another server via technologies like RabbitMQ or any similar message brokers but this will require having separate workers also that will listen to the messages or poll for them and implement the logic.

Handling User-Supplied URLs Safely (SSRF Mitigation)

When I added the ability to submit a GitHub file URL instead of pasting code directly, I ran into a security problem that's easy to miss: SSRF, or Server-Side Request Forgery.

The naive version of this feature is simple, take the URL the user gives you, and have your server fetch it. The problem is that "your server fetches it" part. The request doesn't come from the user's browser, it comes from your backend, using your backend's network position. If you don't restrict what URLs are allowed, an attacker isn't limited to real GitHub files, they can point your server at internal services, cloud metadata endpoints, or anything else your server can reach that the hackers normally couldn't.

So a URL field isn't just an input validation problem, it's a "what is my server willing to do on someone else's behalf" problem.

For handling this, I enforced exact host match on raw.githubusercontent.com, and prevented any redirections when requesting the submitted URL.

Integration with LLM and controlling the usage cost

When you call the LLM to integrate it in your system, you don't just send the code. You send two things every single call:

1. System Prompt
This is your instructions to the LLM, it never changes between calls. It tells the LLM who it is (the persona) and what to do. It is something like:
"You are a code review assistant. Analyze the code you receive and return ONLY a JSON object with an issues array. Each issue must have: line number, severity (error/warning/info), type, and message. Never explain yourself. Never add text outside the JSON."
This is how you force structured output, short and structured JSON and nothing else. Without it, the AI would respond in plain English like a human, and this is hard to process in the code also it makes your output tokens explode and thereby your cost.

That's exactly why the system prompt exists, to say "return JSON only, no explanations", it's not just about structure, it's also cost control. Furthermore, you handle edge cases through the system prompt, like telling the LLM that if the inferred language of the code snippet does not match the language field that is sent with the request, then return language mismatch, instead the LLM returns many compilation errors as the language is different, which is unnecessary cost.

2. User Message
This is the actual code the user submitted, and LLM deals with it according to the instructions in the system prompt. This changes every call according to the request data, this is the "What to handle". System prompt is the "How to handle".

Software Design (Architecture and Patterns)

I was building my application without caring about this at the beginning, but when I needed to perform Unit Testing, I realized that my code is tightly coupled and needs refactoring. So, in the next sections I will specify what did I design and build exactly.

Clean Architecture

When thinking in this project, it appears that it aligns well with the Clean Architecture. It has external dependencies like database, LLM, webhook notifying and GitHub integration, so they should be isolated in Infrastructure Layer. Inside this layer, I designed it to contain implementations for LLM clients that their job is only to communicate with LLM providers and it absolutely never do anything related to the business logic, and to contain implementations for repositories. Then I built an Application Layer that orchestrate the business workflow and decisions, so it talks to the infrastructure layer without being dependent on it, achieving loose coupling between layers.

This aligns with the Single Responsibility Principle. Also, it makes the codebase more testable as it isolates the client and make all the business workflow orchestration only inside the Application Layer. Now if I want to write unit tests, I will never care about the client as it is simply integration details, no need to consider them in unit testing.

Adapter design pattern

Appears in LLM client. It adapts the different responses of different LLMs, and give standard response to the Application Layer. So, the client itself adapts the internal shape of data to be compatible with the standard DTO defined inside the Application Layer.

Repository Design Pattern

Generally, having repository pattern with EF Core is actually a bad practice. The truth is EF Core itself applies repository pattern and unit of work pattern. So if you tried to implement repository pattern, it will be just wrapper methods over the EF Core, and it will hide the power of using EF Core directly and controlling the queries and commands via LINQ.

But in my case, I decided to have a repository pattern, actually I felt that it is important. In my case I just need some operations like: changing status, saving review result in the database or get review by ID. I did not need to delete anything or to generally update the records, I just needed to update specific fields and add new or get by ID, so in my case I found that it is better to have this layer that will introduce to me better API to use inside the application layer and fits better to my needs. Furthermore, the repository pattern here to achieve more loose coupling, and higher testability by using the interfaces and mocking, so it is a trade-off.

Integrating with the AI Agent

I wanted to explore what it means to make a service agent-ready, not just API-ready. I wanted to make the AI agent to become another consumer of the API, so not only frontend clients can use my service via APIs, also the AI agents via MCP Server.

What is MCP Server

AI Agent (more accurately, Host) contains two relevant pieces: the LLM (that is responsible for the reasoning) and the Client (that communicates with MCP servers).

The MCP server is essentially a layer for AI agents to use the API. REST API endpoints are great for developers building frontends that consume the API directly, but if you want AI agents to call your API endpoints, then you need this extra layer, the MCP server, communicating with AI agent either over stdio or HTTP, depending on whether it runs locally on the same machine as the agent, or the server is deployed online.

Docker Image

Docker image of the local MCP server is available in the packages section in the repository.

mazenaly256 / LINTelligent

AI-integrated backend service for code linting (i.e. analyzing code for issues), with an accompanying MCP server for AI-agent integration.

LINTelligent

AI-integrated backend service for code linting (i.e. analyzing code for issues), with an accompanying MCP server for AI-agent integration.

Overview

A code snippet is submitted in a linting/reviewing request, either as a direct snippet in the request body or via a public GitHub file URL.

View on GitHub

Communication between AI Agent and MCP Server

AI agent (especially the Client) does the MCP handshake via 'initialize' request to get more info about the MCP server and its capabilities then it sends 'tools/list' to know each server's tools, and the same with prompts with 'prompts/list' and resources with 'resources/list' so agent can can invoke those things when it needs. All happening at connection startup, before any actual request for any specific resource, prompt or tool. The actual request happens after that, when LLM decides to use any thing from these available tools during the reasoning loops.

Wrap-up

One of the things I learned in this project is what loose coupling really means in practice, I started with a tightly-coupled codebase in the beginning then I had to refactor the whole codebase and architecture to make it testable and write good unit tests.

I learned many things from this project and shared with you some of them, I hope anyone can learn anything from this blog post or even take a glimpse on something new that can explore more deeply.

Cinema Seat Reservation System — Part 3: Problems, Decisions and Some Areas Of Improvement

Mazen Aly — Tue, 14 Jul 2026 09:11:09 +0000

Introduction

In the two previous parts, I finished sharing my main checkpoints while I was building the system till I deployed it. Today, I need to share two interesting problems that faced me and how I took decisions to solve them. I hope someone can benefit from them.
Also, I will mention the areas of improvement in the system, how it can be better and considering their negative consequences on the system. System design is all about Trade-offs.

You can find more decisions regarding the system in /docs/decisions/ folder on GitHub repository.

mazenaly256 / Cinema-Seat-Reservation-System

Cloud-native microservices-based cinema seat reservation system developed. Designed for modularity and scalability.

Cinema Seat Reservation System

A cloud-native, microservices-based ecosystem developed in ASP.NET Core with REST APIs. This system features deliberate design decisions optimized for modularity, scalability and resilience — implementing proven distributed systems patterns such as Retries and Circuit Breakers and Request Timeouts alongside automated CI pipelines and manual deployment workflow.

Architectural Overview

Diagram

Services

Service Responsibility

API Gateway Centralized authentication, rate limiting, request timeouts, and routing to the main services

Identity Service Centralized Identity Provider — user management and JWT issuance

Movie Service Movies and showtimes management

Reservation Service Seat layout, seat holds, and seat reservations

Getting Started

The system is live and ready to test via Postman Workspace

The workspace includes:

Complete API documentation, with organized request collections and folders for each service

All API endpoints with example requests and responses, featuring interactive testing

Pre-configured variables containing hosting Azure VM IP with ports to access the services

How to…

View on GitHub

Service	Responsibility
API Gateway	Centralized authentication, rate limiting, request timeouts, and routing to the main services
Identity Service	Centralized Identity Provider — user management and JWT issuance
Movie Service	Movies and showtimes management
Reservation Service	Seat layout, seat holds, and seat reservations

Problems

Latency Problem

One of the bottlenecks that appeared through load-testing, is that the latency of a specific endpoint (Get all showtimes with filters) takes the latency was around 850ms.

Availability Problem

Availability is simply the ability of the system to be alive and respond to requests, and do not completely die.

Another problem appeared when I tried to stress test the system, I simulated huge traffic on the system and it was across the critical path in the system (that is the longest trip for a request across the services).
Due to the large traffic the service took long time to respond, and also under stress testing the service crashed, due to exceeding the memory that limit that I determined for the container.

Furthermore, from a user experience perspective, a service that returns a quick, graceful error is far better than one that hangs indefinitely. Under stress testing, the P95 latency reached a painful 16 seconds, a frustrating experience where users are highly likely to lose patience and abandon their requests entirely.

Decisions To Solve The Problems

Solution of Latency Problem

I accepted the idea that the latency has to be slightly high, due to the network overhead that caused by having the database and service running on different servers in different countries so there is a long trip for data over the network between the service and database, but the 850ms latency is also very high even if we consider the network delay, there must be a problem with my system design.

At first glance, since the problem was related to database reading operations (data retrieval), then database indexing and caching are obvious answers to improve performance and reduce latency, but guess what? Neither of them was the solution in my case.

Why indexing did not reduce the latency:

Generally, indexing is a go-to solution in cases like this and I already created a database index on the table, but guess what? There was not any reduction in latency.
What I learned is that due to the high latency, and the relatively small number of rows (which is ~10,000 rows), the impact of indexing on the latency is invisible especially since the network delay itself was already massive.

Why caching is not a solution (common problems in both distributed and in memory):

Actually, I found caching would make things much worse, there are many cons for caching my situation:

Range-based queries (from and to date filters) produce highly variable cache keys as if data of 2 days is requested then data of five days that span those two days is requested again, then actually we absolutely need to hit database again as we do not know if there are showtimes in those excess 3 days or not, cache usage rate would be low.
Also full-list caching becomes impractical as the dataset grows to 100k+ rows.
Cache invalidation on create/update/delete for the domain resources adds complexity that it actually does not pay off.

Those are problems in both in-memory and distributed caching, but even each one has specific cons.

the main problem with the in-memory caching is in a multi-containered deployment, each container instance maintains its own isolated cache, this produces inconsistent responses, as each container will have its own data separately — unacceptable for a booking system. Furthermore, syncing all those data will add significant complexity.

also in my case distributed caching (via Redis or any similar) will introduce its own network overhead to transfer data between the service and the Redis instance, that introduce more network delay that will increase latency.

The real solution, eliminating unbounded query results

It is pagination, instead of retrieving huge number of rows for a single request, return only a few number of rows like 10 or 20. Practically speaking, users never need more than them, they will see them and if they need more, they can load more and in this case they will accept waiting a few additional milliseconds to see new 10 or 20 showtimes, instead of waiting 850ms to retrieve 10,000 rows that user will never consider them all. This solution improved the performance reducing the P95 latency to ~515ms, and increased the throughput (the handled traffic) by ~25%.

Theoretically, there is an issue here that may require changing the pagination technique, the issue is that the database still reads every row it skips. Page 5 is fast. Page 5000 is slow. This becomes visible only when the number of becomes really huge.
However, practically speaking, this number of rows will not requested as it require very long date window that contains this enormous number of showtimes, that is not requested in the real life.

Solution of the availability problem

To solve this I applied rate limiting on the API gateway, this ensures that any traffic exceeding or limit fails at the edge, guaranteeing that only a manageable number of requests are processed within a given time window.

Additionally, applying request timeouts helped as it prevented misbehaving requests that are unusually slow for some specific reason from degrading all the system as they take long time to be processed and take some resources. Now the system automatically cancels any request after 8 seconds and disconnect all the related connections and frees up all its allocated resources to be available to another incoming request to consume.

And prevented the latency from exceeding 8 seconds.

Possible Areas of Improvement

In this section I would like to say that honestly, I do not know if these features will actually improve the system, or their effect will be minimal. For sure they will come with their overhead and trade-offs and will require a decision to determine whether they will introduce an actual improvement.

1. Caching

I discussed the caching when addressing the latency problem and I mentioned why it did not work, but caching may be useful in another part in the system specially when service is read heavy, and also with data that do not change frequently or the data that the way of querying them is consistent (that was not the case in my problem above).

2. Event-Driven Architecture and Message Brokers like Kafka and RabbitMQ

At first glance, this solution clearly introduces a major architectural trade-off: Database Replication. On the other hand, it has benefits including that no inter-service network calls are required so the system will be faster, and also no cascading failures, suppose that movie service crashed, the reservation service has all data on its database replica and can actually use and do its work (reserving seats in showtimes) without even knowing that movie service is down.
This will reduce the synchronous HTTP calls that happen frequently between the services in cases like checking movie when adding a new showtime, or checking showtime when trying to reserve a seat. All those are synchronous calls that enforce the upstream service (service that makes a call) to wait for the downstream service (the called service) to respond. Also upstream service fails to do its job if the downstream service goes down.

3. Change the database location

There are two options to achieve this.
Option A: is to just get a nearer the server for our database. There is no architectural side effects and never presents more challenges, just host the DB on a nearer server to the deployment server of the services, this reduces the travelling distance for data thereby reduce network overhead.

Option B: is hosting the database on the same machine as the services, this will be actually better in terms of performance due to eliminating the network overhead. But it will introduce its own overhead like the configuration headache and managing the DBMS on the server.
Additionally, it comes with a trade-off, which is coupling the downtime of DB with the downtime of the system. When the services and the database are hosted on different servers, the services can still be available and return friendly errors when the DB server can not be reached, instead of being fully down if they all are on one machine. This is a violation for the principle of single point of failure, that is "eliminating cascading failures by separating concerns across different machines", but as I said above ad want you to remember: System design is all about Trade-offs.

Cinema Seat Reservation System — Part 2: Transitioning To Production-Scale and Deploying on Azure Cloud

Mazen Aly — Wed, 24 Jun 2026 06:26:12 +0000

Introduction

This is the second part of sharing my journey to create a microservices-based backend system, in the previous part, I introduced the system and its services.
In this part I am going to mention the main things that happened with me from then until now.

Transitioning to online DBaaS platforms

The first main thing was to transition my databases from my local device to accessible over the internet. I used Neon and MongoDB Atlas. Although performance-wise it is better to deploy the database on the same server that the whole system so all services can access the databases without network overhead, This solution is better from a point, that is avoiding consuming the free VM instance that I got to host my main services, as with DBaaS platforms I will not require storage for databases or additional overhead to handle the DBMS on a free small resources-constrained VM.

Observability

Observability is one of the main concerns in any system, it gives the ability for the system to expose what happens inside it without any need to guess and manually trace the code to determine where the error may happened.
I utilized OpenTelemetry, as I found it is most used and accepted tool to log, trace and collect metrics about the system and the traffic. Also, I loved that it is not related to specific framework, that is .NET by the way, I loved the idea that it is standalone tool.
But logging and tracing and metrics collection will not be beneficial if we do not see it actually and can achieve monitoring from those telemetry data, so I used Grafana Cloud to export the telemetry data to some place that is accessible online and a tool that can generate dashboards and visualizing for the metrics (Prometheus), and UI that can show all the telemetry data easily.

Resilience

I achieved resilience in this system, by implementing Retry and Circuit-Breaker Pattern, that applies retires and mitigates the effect transient failures, so user can not know that there is actually a failure happened.
Without it, any HTTP transient failure when calling a downstream service will lead to Internal Server Error response directly, even there is no permanent failure in the downstream service.

Deployment

Until this point, we have a system that is fully functional and have consistent docker configuration for its services via Docker Compose, and it database is already there and available.

Now this is the point at which I wanted my system to be online and accessible from everywhere over the world, and really reach the goal: From Baseline Local Development To Live Cloud-Native Production.

For this I chose Azure Cloud Services, I had a virtual machine on Azure Cloud and installed Docker on it, also I configured the firewall so it added two ports to access my system, one for Identity Service, and the another one is for API Gateway.

What I did is as follows:

I created images from my actual code on my local machine, and pushed it to GitHub Container Registry.
I issued a token from GitHub to allow Docker engine that is installed on the virtual machine to actually pull and push the images (it is called Packages of type containers on GitHub) from and to my GitHub account.
I copied (via SCP) Docker Compose file with secret env variables file, from my local machine to the online Azure VM. Now the VM has Docker engine, and the ability to access any uploaded images on GitHub and pull/download them on the VM.
Finally, I executed the command: docker compose pull to pull images from GitHub Container Registry then docker compose up and to spin up the containers from them.
Voilà! the system became live and accessible online.

And now, we have a live production-scale cloud-native application.

See GitHub Release, Capturing Project at This Point

Workflow

After I had this whole setup, my workflow became very consistent, it is as follows:

Make a change in the code, fixing a bug or enhance codebase or add a feature, then push it to GitHub, every change should be pushed to GitHub to achieve CI (continuous integration) practice in software development, that is simply the practice of merging the new code changes to the branch and then get automatically tested and checked, and this is achieved by the CI Pipeline that I built using GitHub Actions.
Then I directly rebuild the images so I get the latest changes on the code reflected on the new images.
I push these latest versions of images to GitHub Online Registry.
I access the VM through SSH, delete the old docker-compose.yml and .env files if they are modified.
Rerun the docker compose commands to pull the latest images from GitHub Container Registry and spin up new containers and delete the old containers. So, CD (Continuous Deployment/Delivery) is achieved here (manual CD workflow).

Conclusion

In conclusion, I want to say that this project made me learn many valuable skills, concepts and tools. There are many another things that not mentioned to keep things brief (you can get some of them by taking a look on GitHub Repository that is mentioned in Part 1 from this series, and view the commits history), and focus on the points that I feel that it really matters and think that readers can learn from it.

Take a look on this series title, we really transitioned from "Baseline Local Development" that is the MVP that runs on my machine, to "Live Cloud-Native Production" that actually appeared in observability setup and deploying on Cloud and making it accessible online.

If you have questions or feedback, drop them in the comments. I hope I can learn from or add benefit to one of you

Next Steps

For now, I am testing the system to determine its bottlenecks, for sure it has many areas of improvement, and things that even can be added to this project to make it better and more performant, I am going to mention some bugs and issues that faced me and how I overcame it and learned from them and some decisions that I made in the system. This what I will mention in the next part "Bugs, Decisions and Areas Of Improvement".

Cinema Seat Reservation System — Part 1: Overview & Architecture

Mazen Aly — Tue, 26 May 2026 08:11:09 +0000

Introduction

I am writing this series of blog posts to document what I am learning while building a project. You are welcome to criticize and guide me toward areas of improvement — or maybe, and I genuinely hope this, I can introduce you to concepts or ideas you haven’t encountered before, so we both can grow. I will focus on architectural and design concepts and the technologies that can be applied regardless of your framework and programming language of developing the application.

GitHub Repository

There you can find more details, including ADRs (Architectural Design Records) and more extensive documentation.

mazenaly256 / Cinema-Seat-Reservation-System

Cloud-native microservices-based cinema seat reservation system developed in ASP.NET with REST API, featuring deliberate system design decisions. Designed for modularity and scalability.

Cinema Seat Reservation System

A cloud-native, microservices-based ecosystem developed in ASP.NET Core with REST APIs. This system features deliberate design decisions optimized for modularity, scalability and resilience — implementing proven distributed systems patterns such as Retries and Circuit Breakers and Request Timeouts alongside automated CI/CD pipelines.

Architectural Overview

Diagram

Services

Movie Service: Responsible for movies and showtimes.
Reservation Service: Responsible for seats layout representation and seat reservation.
Identity Service: Acts as the centralized Identity Provider (IdP) for the system.
API Gateway: Centralizes the logic of authentication and applies rate limiting, timeouts, and routing policies for all incoming traffic.

API Documentation

Postman API Workspace

View on GitHub

System Overview

I have built a microservices-based backend system, for handling seat reservations in a cinema, each service has its own database. I applied many new concepts that I have learned including how to split the system and build the architecture that offers the modularity and future scalability for the application, building and securing API endpoints using JWT, implementing an API gateway to be the single entry point for my whole system, building a basic CI Pipeline using GitHub Actions, containerizing the services with configuring and running together via Docker Compose.

Services

Movie Service: Responsible for CRUD operations on movies and showtimes, and enforces role-based access control.

Reservation Service: Responsible for handling seats availability checks and the logic of seats reservations and payment.

Identity Service: Acts as the centralized Identity Provider for the whole system, responsible for storing and managing users and issuing JWT tokens that are trusted across all the system.

API Gateway: The single entry point for the system, acting as an architectural AOP (Aspect-Oriented Programming) layer. It centralizes cross-cutting concerns like authentication, rate limiting, and request timeouts in one place instead of duplicating their logic across all the system services. In addition to the main responsibility of API Gateway that is forwarding the requests to downstream services.

System Architecture

GitHub Release

Next Steps

What I am going to do in my next few posts, is to document the main points of transitioning this system from the development phase on my local machine to a fully deployed, cloud-native, production-scale system.