DEV Community: Kenan Sejmenović

Claprec: Engineering Tradeoffs - Limited time vs. Perfection (6/6)

Kenan Sejmenović — Fri, 22 May 2026 11:53:18 +0000

Series Roadmap

Product Overview (1/6)
Inside the Architecture - N-Tier, decoupling, microservices (2/6)
Frontend - Angular, NgRx, and OpenAPI Integration (3/6)
Machine Learning in Practice (4/6)
Database Design and Data Modeling (5/6)
Engineering Tradeoffs - Limited Time vs. Ideal Architecture (6/6)

Closing the Chapter: When "Good Enough" is the Engineering Solution

After a year and a half of active development, countless commits, and a steep learning curve, Claprec is finally shipped. This series has documented the journey, but this final post isn't just a victory lap. It is a retrospective on the gritty reality of engineering tradeoffs.

We often read about architecture in a vacuum - perfectly scalable, perfectly optimized. But in the real world, constraints exist. This post covers the tension between limited time and perfection, the architectural debt accumulated, and why I chose to ship a functional app rather than pursue an unattainable ideal.

The Timeline and The "Last 99%"

The first commit for Claprec dates back to October 19, 2022. It wasn't a continuous sprint; life happened. I graduated, worked for a year as a Frontend Engineer, and juggled other projects. However, the final push took everyone's favorite timeline: the "last 1% of work", which inevitably consumes 99% of the effort.

For the last two and a half months, I dedicated intense focus to finishing the app. There were no strict deadlines (post-graduation), only a self-imposed drive to close this chapter.

The result? A functional application. It follows the programmer's iteration mantra:

Make it functional. (Status: Done)
Make it performant. (Status: Acknowledged, deferred)
Make it beautiful. (Status: Secondary priority)

For a demonstration of skills and a valid product delivery, functional is sufficient.

Architectural Decisions: The N-Tier Constraint

One of the defining constraints of this project was the architectural requirement: N-Tier Architecture.

If I were starting from scratch today with total freedom, I would likely lean towards Clean Architecture for better dependency inversion and maintainability. However, N-Tier was a requirement for my university curriculum, and it taught me a critical lesson: strict boundary enforcement.

The Trap: The Distributed Monolith

My biggest mistake in the early stages was being loose with tier boundaries. I paid the price later. Refactoring a specific part of the primary microservice to restore proper separation of concerns took me two intensive weeks of full-day work.

In N-Tier, if you aren't strict, you are heading for a disaster.

The Silver Lining: Velocity

Despite the complexity of N-Tier, there is a distinct advantage: speed of entity creation. Once the layers are in place, adding a new entity with full CRUD functionality is incredibly fast. This allowed me to build out the backend logic rapidly when I needed to.

Performance and Scalability: The Reality Check

Let's be honest about the state of the shipped product. The application is visibly slow.

The Immediate Missing Piece: There is no caching layer.

Immediate priority: Implementing Redis to offload read pressure and reduce latency would be the first commercial step. Without it, the database takes the full hit of almost every request.
Media delivery: For media files (pictures and documents), I would use a CDN. A key advantage is that the database and the backend already support this setup, so the infrastructure is ready for integration whenever a CDN is provisioned.

The Deployment Reality

Current setup: Deployed to a VPS using Docker and Nginx.
Why: It works. It was fast to set up.
The tradeoff: This is not a scalable architecture for a million-user startup. It is a monolithic deployment on a single node.

The Cloud-Native "What If"

If I were architecting this for high-scale production, the roadmap would look vastly different:

CI/CD: GitHub Actions for automated testing and deployment pipelines.
Orchestration: Kubernetes (K8s) for auto-scaling and self-healing.
Infrastructure as Code: Terraform for reproducible cloud provisioning.
Observability: Prometheus + Grafana for real-time metrics and alerting.

While the current VPS setup lacks the bells and whistles of a cloud-native stack, it fulfills the project's primary goal: it works.

Technical Debt & Hard Lessons

Engineering maturity isn't about writing perfect code; it's about knowing which corners to cut and understanding the cost of doing so. Here is my itemized bill of technical debt:

The Debugging Gap

A key mistake was not measuring execution times during development. I treated performance as an afterthought rather than a feature. This led to "visibly slow" endpoints that require painful retrospective optimization.

Thread Safety Nightmares

I initially neglected thread-safe operations. This was a significant mistake. It produced elusive bugs that I had to solve later - often under pressure. Lesson: concurrency issues do not fix themselves; they compound interest.

Polyglot Persistence

Retrospectively, forcing a relational database for everything was a mistake.

Better Approach: Use specialized storage. For example, a write-optimized time-series database for activity logs, and NoSQL database for archives and logs. This separation would significantly improve performance by aligning each data type with a storage system optimized for its access and write patterns.

The Frontend Grind: 101 Pages

On the frontend, the tradeoffs are visible. I built 101 pages under tight deadlines.

UX Polish: Sacrificed.
User Flows: Inconsistent in places.

This is the reality of feature completion. In a startup environment, often "it works" beats "it looks perfect".

Evolution of Tooling: LLMs

This project was started before ChatGPT existed. Throughout the lifecycle of Claprec, I witnessed the explosion of LLMs.

I integrated them into my workflow, watching the tooling evolve. They are fantastic helpers for some parts of software engineering - generating boilerplate, clarifying language details, writing tests, and drafting standard functions.

However, this journey reinforced a crucial distinction: actual engineering and debugging cannot be fully solved by LLMs. LLMs, built on gradient descent and backpropagation, are powerful tools, but they cannot solve novel problems that haven't been documented on the internet yet. You still need to know what to ask and why the answer works.

Bonus: Book Recommendations

Throughout the development of Claprec, I read a few books to help guide my decisions. These are of quality and I highly recommend them:

RESTful Web Services Cookbook by Subbu Allamaraju was extremely useful for the backend. It helped me design my API, ensuring that the result is a standardized REST API that strictly follows REST practices.

On the frontend side, Universal Principles of UX by Irene Pereyra and Refactoring UI by Adam Wathan & Steve Schoger were very helpful resources. They provided the theoretical and practical advice I needed to navigate the design process.

Closing the Chapter

Claprec is not perfect. It is slow in places, the UX needs polish, and the architecture carries the scars of university constraints. But it is a bridge between academic theory and real-world product delivery.

This project tested my endurance and discipline. It is a testament to the fact that finishing is a skill in itself.

If you prefer video format, I also published a video containing all six videos from the LinkedIn series in their original, unmodified form and sequential order, providing high-level overviews of the engineering decisions behind Claprec: Watch it on YouTube.

What's Next?

I am closing the book on Claprec to focus on new challenges.

Side projects: I'm considering new challenges: engineering a system capable of handling 3 million HTTP requests per second, learning TLA+ or Verilog, or working on an interesting embedded systems project.
Professional opportunities: I am open to new roles. If my experience with Claprec (.NET, Angular, MSSQL) - along with my experience in Next.js (React), Vue.js, Laravel (PHP), Node.js, and Python - matches what you or your company needs, let's talk (Linkedin).

I want to acknowledge Haris Kordić for contributing during the initial stages of the project, including the product vision, design prototypes, and backend implementation.
I also want to acknowledge Benjamin Markanović for his feedback on design decisions throughout the project, and Haris Sejmenović for helping with testing and validating the application before release.

Thank you for following this series.

If you enjoyed this deep dive, please feel free to connect with me on LinkedIn. I will be posting a special closing update there shortly where I share a personal milestone: receiving the Rector's Award for academic achievements.

It is good to close this chapter. Now, onto the next build.

With the series now complete, I'd love to hear your thoughts on these tradeoffs or the entire project in the comments below.

Claprec: Database Design - Modeling the Data (5/6)

Kenan Sejmenović — Wed, 20 May 2026 11:41:14 +0000

Series Roadmap

Product Overview (1/6)
Inside the Architecture - N-Tier, decoupling, microservices (2/6)
Frontend - Angular, NgRx, and OpenAPI Integration (3/6)
Machine Learning in Practice (4/6)
Database Design and Data Modeling (5/6)
Engineering Tradeoffs - Limited Time vs. Ideal Architecture (6/6)

The Blueprint of the Data Model

When building Claprec, I knew that database design couldn't be an afterthought. It wasn't just about storing data; it was about modeling the lifecycle of that data. The requirements were strict: nested comments, recursive categories, complex business and product hierarchies, and critically - enterprise-grade auditability.

I used EF Core's code-first approach, defining the schema from the domain model.

In this post, I'll walk you through how I architected the data layer for Claprec. I prioritized a fully normalized schema designed for performance and legal compliance, moving far beyond simple CRUD operations.

Before diving into the implementation details, it is important to visualize the data architecture as a whole. The system is supported by two distinct databases: the primary transactional database and a separate database for the ViewsProcessing microservice.

First, the main database schema visualizes the core domain. This ER diagram highlights the three layers of the dual-schema strategy: the live tables, the archive schema (<<shadow_deletable>>) for deleted records, and the log schema (<<loggable>>) for audit trails.

Secondly, the database used by ViewsProcessing microservice is kept entirely separate. This schema is stripped down to the essentials for tracking views, ensuring that high-volume analytical writes are isolated and do not impact the performance of the primary transactional database.

With these structures in mind, here is the breakdown of the most significant architectural challenges and solutions.

The Dual-Schema Strategy: Auditability and Data Lifecycle

The most significant architectural hurdle was managing data retention without sacrificing performance. In a production environment, hard deletes are rarely acceptable - especially when legal disputes or behavioral analytics require a full history of user actions.

I solved this by implementing a Dual-Schema Strategy. Instead of cluttering primary tables with IsDeleted flags (which ruins indexing and query performance), I physically moved deleted records to a separate archive schema.

Architecture Breakdown

Primary schema: Lean, hot tables optimized for reads and writes.
Archive schema: Soft-deleted records are physically moved here.
Log schema: A complete audit trail snapshotting every modification.

This separation ensures that the primary database remains lean. When a user deletes a comment, the data isn't just marked; it's architected out of the active set but preserved for compliance.

To achieve this, I built a "write-once, audit-everywhere" mechanism. I didn't want to write manual audit logs in the business logic - that's brittle and prone to human error. Instead, I engineered an automated solution using EF Core Triggers and Reflection.

The entities are decoupled into three distinct layers to support this:

Abstraction: Real data properties (int, string, etc.).
Concrete: The EF Core entity used in queries (handling navigation properties).
Changed/Deleted: Shadow entities that inherit from abstraction but implement tracking interfaces (IChanged, IDeleted).

When an entity is modified, the backend inspects the change, captures the previous state via reflection, and persists it to the corresponding audit table automatically.

// AbstractionReview.cs

[Table("review")]
public abstract class AbstractionReview : AbstractionCommentOrReviewParent
{
    [Column("product_or_business_parent_id")]
    public long ProductOrBusinessParentId { get; set; }

    [Column("business_address_id")]
    public long? BusinessAddressId { get; set; }

    [Column("rating")]
    public byte Rating { get; set; }

    [Column("description")]
    [MaxLength(255)]
    public string? Description { get; set; }

    [NotMapped]
    public override long ViewCount { get => base.ViewCount; set => base.ViewCount = value; }

    [NotMapped]
    public override long UserId { get => base.UserId; set => base.UserId = value; }

    [NotMapped]
    public override DateTime CreatedAt { get => base.CreatedAt; set => base.CreatedAt = value; }
}

// Review.cs

public class Review : AbstractionReview
{
    [ForeignKey(nameof(Id))]
    public CommentOrReviewParent CommentOrReviewParent { get; set; } = null!;

    public BusinessAddress? BusinessAddress { get; set; }
    public ProductOrBusinessParent ProductOrBusinessParent { get; set; } = null!;

    [NotMapped]
    public User? User { get; set; }
}

// DeletedReview.cs

[ShadowDeleteable("review")]
public class DeletedReview : AbstractionReview, IDeleted
{
    [Column("deleted_id")]
    public long DeletedId { get; set; }

    [Column("deleted_at")]
    public DateTime DeletedAt { get; set; }

    [Column("deleted_by")]
    public long? DeletedBy { get; set; }
}

// ChangedReview.cs

[Loggable("review")]
public class ChangedReview : ChangedAbstraction, IChanged
{
    [Column("review_id")]
    public long ReviewId { get; set; }

    [Column("rating")]
    public byte? Rating { get; set; }

    [Column("description")]
    [MaxLength(255)]
    public string? Description { get; set; }
}

Automating Entity Registration: Reflection over Repetition

One of the code-smells in Entity Framework Core is a DbContext with hundreds of DbSet properties and manual fluent API configurations. With Claprec's complex schema, this was cumbersome.

I automated the entity registration process. Instead of manually adding entities, the AppDbContext scans the executing assembly for types matching specific interfaces (IChanged, IDeleted). It identifies the concrete types and automatically registers the necessary triggers.

This didn't just save lines of code; it enforced consistency. If a developer creates a new entity, they simply implement the interface, and the database context handles the wiring, triggers, and schema mapping automatically.

// AppDbContext.cs

// ...

private IEnumerable<Type> GetEntitiesInRepository(string namespaceFullName)
{
    return from t in Assembly.GetExecutingAssembly().GetTypes()
        where t.IsClass &&
              t?.Namespace != null &&
              t.Namespace.Contains(namespaceFullName) &&
              !t.IsAbstract
        select t;
}

private void AddChangeTriggers(DbContextOptionsBuilder optionsBuilder)
{
    var changedTypes = GetEntitiesInRepository(ChangedNamespaceFullName);

    foreach (var changedType in changedTypes)
    {
        CheckIfTypeImplementsIChanged(changedType);

        var concreteType = FindConcreteType(changedType, _loggableEntitiesNamespaceName);

        RegisterTrigger(optionsBuilder, typeof(AfterChangeTrigger<,>), concreteType, changedType);
    }
}

private void AddDeleteTriggers(DbContextOptionsBuilder optionsBuilder)
{
    var deletedTypes = GetEntitiesInRepository(DeletedNamespaceFullName);

    foreach (var deletedType in deletedTypes)
    {
        CheckIfTypeImplementsIDeleted(deletedType);

        var concreteType = FindConcreteType(deletedType, _shadowDeletableEntitiesNamespaceName);

        RegisterTrigger(optionsBuilder, typeof(AfterDeleteTrigger<,>), concreteType, deletedType);
    }
}

// ...

Performance Engineering: Seeding and Garbage Collection

Data lifecycle management is one thing; initializing it is another. I faced a massive performance bottleneck during database seeding.

The dataset includes 374,352 cities and 720,599 zipcodes. When I first implemented seeding using standard EF Core AddRange, the full seed took roughly 40 minutes. This was unacceptable for a development workflow where database resets are frequent.

I knew the primary culprit was Entity Framework Core's change tracker - maintaining state for hundreds of thousands of entities incurs massive overhead. I attempted to optimize this by explicitly detaching entities immediately after insertion to unburden the tracker. While this yielded some performance improvements, they were marginal - nowhere near the speedup required for a rapid development cycle.

The Fix: Raw SQL and Batch Processing

I decided to bypass EF Core's pipeline entirely for these bulk operations and wrote raw SQL statements directly.

// SeedCity.cs

private const string INSERT_STATEMENT_2 = "INSERT INTO dbo.city(city_id, country_id, name, lat, lng) VALUES ({0}, {1}, N'{2}', {3}, {4});";

However, this introduced a new problem: memory spikes.
Constructing hundreds of thousands of SQL strings in memory overloaded the RAM, causing the app to crash. The .NET Garbage Collector (GC) is optimized for steady-state workloads, but it cannot compensate for extreme, one-time allocation spikes.

I implemented batch processing and manual GC triggering:

The SeederManager is configurable: batch size, target environment (Dev/Prod), and collection type.
After processing a batch, it manually triggers the garbage collector to immediately free RAM.

Result: The full database seed time dropped from ~40 minutes to ~30 seconds (~98% reduction).

// Program.cs

// ...

await startup.PopulateDb(false, 10, 25000);

// ...

// Startup.cs

// ...

public async Task PopulateDb(bool loadAllData, int geodataSubsetLength, int maxNumberOfStatementsPerExecution)
{
  // ...
}

// ...

// SeedCity.cs

// ...

public async Task Seed()
{
  // ...

  var sb = new StringBuilder(listCapacity);

  foreach (var geoItemCountry in _geoItemCountries)
  {
    foreach (var geoItemCity in geoItemCountry.Cities)
    {
        if (count > _maxNumberOfStatementsPerExecution)
        {
          // ...

          await _appDbContext.Database.ExecuteSqlRawAsync(sb.ToString());

          sb = null;
          sb = new StringBuilder(listCapacity);

          // ...
        }

        // ...

        sb.Append(string.Format(INSERT_STATEMENT_2, geoItemCity.CityId, geoItemCountry.CountryId, geoItemCity.Name, geoItemCity.Lat, geoItemCity.Lng));

        // ...
    }
  }

  // ...
}

// ...

Inheritance Modeling and EF Core Optimization

Claprec requires complex hierarchies. To prevent duplication of fields between the live entity, its archived version, and its log version, I utilized a strict inheritance strategy.

I separate entities into an Abstraction and a Concrete class.

Abstraction: Defines the actual data columns.
Concrete: Inherits the abstraction and defines navigation properties (Foreign Keys).

The reason for this separation is strictly the DRY (Don't Repeat Yourself) principle. Since lazy loading is disabled by default in the architecture, I didn't need to separate them to control loading behavior. Instead, this structure allows the archive entities (like DeletedComment) to inherit directly from the abstraction. This means the archived entity shares the exact same data fields as the live entity without me having to rewrite or maintain two sets of identical properties.

The logging model introduces an additional constraint. Unlike archived entities, where the full state is preserved, log entities track only a subset of fields. Since not every field change is relevant, each log entity explicitly defines which fields are tracked. This avoids unnecessary data growth and keeps logs focused on meaningful state transitions.

This approach also enabled modeling entities with multiple parent relationships via navigation properties and composite primary keys - something EF Core handles relatively well compared to my experiences with Laravel 6.

Why inheritance over duplication?

Single source of truth: Shared fields are defined once and reused across related entities.
Consistent structure: All related entities stay aligned automatically through the shared base definition.
Easier maintenance: Changes to shared fields are made in one place and automatically affect all related entities.

// CreatedAtTimestamp.cs

public abstract class CreatedAtTimestamp
{
    [Column("created_at")]
    public virtual DateTime CreatedAt { get; set; }
}

// AbstractionCommentOrReviewParent.cs

[Table("comment_or_review_parent")]
public abstract class AbstractionCommentOrReviewParent : CreatedAtTimestamp, ICountViews
{
    [Key]
    public long Id { get; set; }

    [Column("user_id")]
    public virtual long UserId { get; set; }

    [Column("view_count")]
    [DefaultValue(0)]
    public virtual long ViewCount { get; set; }
}

// AbstractionComment.cs

[Table("comment")]
public abstract class AbstractionComment : AbstractionCommentOrReviewParent
{
    [Column("comment_or_review_parent_id")]
    public long CommentOrReviewParentId { get; set; }

    [Column("value")]
    [MaxLength(255)]
    public string Value { get; set; } = null!;

    [NotMapped]
    public override long ViewCount { get => base.ViewCount; set => base.ViewCount = value; }

    [NotMapped]
    public override long UserId { get => base.UserId; set => base.UserId = value; }

    [NotMapped]
    public override DateTime CreatedAt { get => base.CreatedAt; set => base.CreatedAt = value; }
}

Optimization Strategies: Indexes and Identity Seeds

To ensure the database scaled, I applied two specific optimization strategies:

Identity Seeds

By default, SQL Server identity columns start at 1. For signed integer types, this uses only the positive portion of the available range. I configured the identity seed to start at the minimum value of the underlying type to utilize the full representable range.

This doubles the available ID pool before a key overflow could theoretically occur - a small configuration change with a significant long-term benefit.

// AppDbContext.cs

private void SetIdentitySeeds(IEnumerable<IMutableEntityType> entities)
{
    foreach (var type in entities)
    {
        var primaryKeys = type.FindPrimaryKey();

        if (primaryKeys!.Properties.Count != 1)
        {
            continue;
        }

        foreach (var prop in primaryKeys.Properties)
        {
            switch (Type.GetTypeCode(prop.ClrType))
            {
                case TypeCode.SByte:
                    type.FindProperty(prop.Name)!.SetIdentitySeed(sbyte.MinValue);
                    break;
                case TypeCode.Int16:
                    type.FindProperty(prop.Name)!.SetIdentitySeed(short.MinValue);
                    break;
                case TypeCode.Int32:
                    type.FindProperty(prop.Name)!.SetIdentitySeed(int.MinValue);
                    break;
                case TypeCode.Int64:
                    type.FindProperty(prop.Name)!.SetIdentitySeed(long.MinValue);
                    break;
            }
        }
    }
}

Heavy Indexing Strategy

I prioritized the use of integer-based keys over string-based ones to improve comparison efficiency and reduce index size. Integer values require less storage and are processed faster by the CPU, enabling more index entries per page, reducing memory usage and disk access, and improving overall query performance.

I also defined Composite Unique Keys to prevent logical duplicates (e.g., a user blocking the same user twice).

// AppDbContext.cs

private void SetCompositeUniqueKeys(ModelBuilder modelBuilder)
{
    _ = modelBuilder.Entity<Zipcode>()
        .HasIndex(z => new { z.CityId, z.Name }).IsUnique();

    _ = modelBuilder.Entity<Block>()
        .HasIndex(b => new { b.UserId, b.BlockedUserId }).IsUnique();

    _ = modelBuilder.Entity<BusinessAddress>()
        .HasIndex(ba => new { ba.Name, ba.Number, ba.CityId }).IsUnique();

    // ...
}

Conclusion

The resulting architecture for Claprec is designed for auditability, traceability, and scalability - not just functional correctness. By leveraging a dual-schema for soft deletes and field-level change tracking, automating triggers via reflection, and optimizing the seeding process, I built a backend capable of handling enterprise-level scrutiny.

What's Next?

While a meticulously designed database provides the structural integrity of the platform, it doesn't answer the question of when to stop building. In the final post, Claprec: Engineering Tradeoffs - Limited time vs. Perfection (6/6), I'll step back from the code to examine the decision-making process. I will discuss the tension between architectural idealism and the reality of shipping a product - where I chose to invest in over-engineering for scalability, where I accepted pragmatic compromises, and how to balance the pursuit of perfection against the constraints of a deadline.

I'd love to hear your thoughts on this database architecture approach or answer any questions you might have in the comments below.

Claprec: Machine Learning in Practice (4/6)

Kenan Sejmenović — Mon, 18 May 2026 11:33:09 +0000

Series Roadmap

Product Overview (1/6)
Inside the Architecture - N-Tier, decoupling, microservices (2/6)
Frontend - Angular, NgRx, and OpenAPI Integration (3/6)
Machine Learning in Practice (4/6)
Database Design and Data Modeling (5/6)
Engineering Tradeoffs - Limited Time vs. Ideal Architecture (6/6)

Building the Recommendation Engine: A Hybrid Approach to Personalization in Claprec

When building Claprec, the primary challenge wasn't just storing reviews; it was surfacing them. The landing page is the gateway to the platform, and a generic "latest posts" feed simply doesn't cut it when you're trying to build user retention. A system was needed that could handle the cold start problem, respect geographical relevance, and leverage user behavior - specifically, how much time a user spends consuming content.

In this post, I'm going to break down the architecture of the recommendation algorithm that powers the main feed. It's a hybrid system combining collaborative filtering via Matrix Factorization, geo-spatial heuristics, and other factors.

The Architecture: Strategies for Different Contexts

One of the first decisions I made was to avoid a "one size fits all" approach. The backend logic needs to pivot based on the client's state. Specifically, are we dealing with an authenticated user with or without location data, or an anonymous user?

The entry point handles these three distinct scenarios:

Anonymous & No Location: The system defaults to a popularity contest, using recency as a fallback metric.
Authenticated User: The architecture deploys a personalized ML-driven feed that prioritizes interests, followed by popularity and recency.
Authenticated User & Location: The logic applies a personalized ML-driven feed that prioritizes geospatial factors, followed by interests, popularity, and recency.

// HigherCrudServiceReview.cs

public async Task<PaginatedResponse<DtoRelatedReview>> Recommended(BaseSearchDto search, UriBuilder uriBuilder, double? lat, double? lng, User? user)
{
  // ...

  return await PaginatedResultWithAttachedProperties(...);
}

Handling Geo-Spatial Complexity

Before we even get to the Machine Learning, we have to solve the location problem. In Claprec, a review isn't just a point on a map. It can be attached to a specific business address, but it can also be attached to a product that is sold across multiple locations.

This required a robust resolution strategy. We don't just check a single column; we traverse a hierarchy. We aggregate coordinates from the specific BusinessAddress, but if the review targets a product, we fetch all business addresses stocking that product. Furthermore, we resolve user locations not just from GPS pings (lat/lng), but also from Zipcode and City-level data provided in their profile.

// HigherCrudServiceReview.cs

// ...

var reviewsLatitudesLongitudes = await PairReviewsWithTheirUniqueLatsAndLngs(reviews);

var latitudesAndLongitudesOfUser = await PairLatitudesAndLongitudesOfUser(user!.Id);

// ...

// HigherCrudServiceReview.cs

private double? CalculateClosestProximity(double lat, double lng, HashSet<(double, double)> latitudesLongitudes)
{
    if (latitudesLongitudes.Count == 0)
    {
        return null;
    }

    var absLat = Math.Abs(lat);
    var absLng = Math.Abs(lng);

    var proximity = double.MaxValue;

    foreach (var latitudeLongitude in latitudesLongitudes)
    {
        var latDiffAbs = Math.Abs(absLat - Math.Abs(latitudeLongitude.Item1));
        var lngDiffAbs = Math.Abs(absLng - Math.Abs(latitudeLongitude.Item2));

        var proximityOfTuple = Math.Abs(latDiffAbs - lngDiffAbs);

        if (proximityOfTuple < proximity)
        {
            proximity = proximityOfTuple;
        }
    }

    return proximity;
}

This logic ensures that when we calculate proximity, we are matching a user's "area of influence" against a review's "area of availability".

The ML Core: Matrix Factorization on Implicit Feedback

For authenticated users, simple sorting isn't enough. We need personalization. I opted for a collaborative filtering approach using Matrix Factorization, but with a twist: we don't have explicit ratings (1-5 stars) for the act of viewing a review. Instead, we rely on Implicit Feedback - specifically, "Time Spent".

When a user stares at a review for 10, 30, or 60 seconds, that is a signal. We treat this duration as the label for the interaction.

Model Training Pipeline

The model is built using Microsoft.ML. The pipeline is relatively standard but effective. We map the UserId and ReviewId to keys and feed the Label (time spent in seconds) into a MatrixFactorizationTrainer.

// ReviewModel.cs

var estimator = mlContext.Transforms.Conversion.MapValueToKey("UserIdEncoded", "UserId")
    .Append(mlContext.Transforms.Conversion.MapValueToKey("ReviewIdEncoded", "ReviewId"));

var options = new MatrixFactorizationTrainer.Options
{
    MatrixColumnIndexColumnName = "UserIdEncoded",
    MatrixRowIndexColumnName = "ReviewIdEncoded",
    LabelColumnName = "Label",
    NumberOfIterations = 20,
    ApproximationRank = 100
};

We set the ApproximationRank to 100 and run for 20 iterations. This balances latency and the ability to capture complex user-item interactions. Although implicit feedback data can be noisy, we train the model to predict how long a user would spend on a review they haven't seen yet, relying on the algorithm to find signal amidst the noise.

Operationalizing the Model: Retraining Strategy

A model is only as good as its data. Retraining a model on every single interaction is a resource drain. To solve this, I implemented a threshold-based retraining trigger.

We maintain a counter for specific activity types (staring at reviews). The model retrains only when the count of new activities hits a specific threshold (e.g., every x new interaction signals from a user). This ensures the model adapts to new trends without crippling the database with constant training jobs.

// HigherCrudServiceActivity.cs

public async Task<DtoPlainActivity> Insert(InsertDtoActivity insert, User user)
{
    // ...

    if (insert.ActivityTypeId is
        (short) EnumActivityType.STARING_AT_REVIEW_FOR_10_SECONDS or
        (short) EnumActivityType.STARING_AT_REVIEW_FOR_30_SECONDS or
        (short) EnumActivityType.STARING_AT_REVIEW_FOR_60_SECONDS
       )
    {
        await TrainReviewModelIfThresholdAchieved(user);
    }
}

private async Task TrainReviewModelIfThresholdAchieved(User user)
{
    var reviewActivitiesOfUserCount = await GetQueryable()
        .Where(a => a.UserId == user.Id &&
                    (a.ActivityTypeId == (short) EnumActivityType.STARING_AT_REVIEW_FOR_10_SECONDS ||
                    a.ActivityTypeId == (short) EnumActivityType.STARING_AT_REVIEW_FOR_30_SECONDS ||
                    a.ActivityTypeId == (short) EnumActivityType.STARING_AT_REVIEW_FOR_60_SECONDS)
              )
        .LongCountAsync();

    if (reviewActivitiesOfUserCount > 1 && reviewActivitiesOfUserCount % THRESHOLD_FOR_REVIEW_MODEL_TRAINING != 0)
    {
        return;
    }

    var reviewActivities = await GetQueryable()
        .Where(a => a.ActivityTypeId == (short) EnumActivityType.STARING_AT_REVIEW_FOR_10_SECONDS ||
                    a.ActivityTypeId == (short) EnumActivityType.STARING_AT_REVIEW_FOR_30_SECONDS ||
                    a.ActivityTypeId == (short) EnumActivityType.STARING_AT_REVIEW_FOR_60_SECONDS)
        .ToListAsync();

    ReviewModel.OrchestrateReviewRecommenderModel(reviewActivities, _webHostEnvironment, reviewActivities.LongCount());
}

The "Buffer" Optimization & Popularity Dynamics

One of the more interesting engineering challenges was pagination. Standard pagination (Skip(x).Take(y)) breaks down when you have a volatile sorting order influenced by ML predictions and volatile proximity.

To solve this, I implemented a Buffer Strategy. Instead of querying the exact page size from the database, we fetch a larger "buffer" (e.g., 100 records) based on a stable initial sort (creation date). We then apply the heavy lifting - ML predictions, proximity calculations, and category matching - in-memory on this buffer.

// HigherCrudServiceReview.cs

// ...

var paginationCreator = new PaginationCreator<BaseSearchDto>(search, uriBuilder, totalRecords);

var bufferPage = paginationCreator.CalcSkippingRecordsCount() / REVIEW_BUFFER_SIZE;

query = query.Skip(bufferPage * REVIEW_BUFFER_SIZE).Take(REVIEW_BUFFER_SIZE);

var reviews = await query.ToListAsync();

// ...

Crucially, this buffer approach mitigates a common pitfall of popularity-based ranking: the "rich get richer" feedback loop. If we ranked the entire database solely by total time spent, legacy reviews would dominate the feed indefinitely, burying new content.

By anchoring the buffer to CreatedAt, we enforce a sliding window of relevance. As new reviews are created, they enter the buffer, and older reviews are naturally pushed out. This ensures that "popularity" is only a deciding factor among recent content, guaranteeing freshness while still surfacing the best of what's new. It keeps the feed from stagnating and ensures that popularity serves as a quality signal for new content, rather than a permanent high ground for the old.

The Ranking Hierarchy

Finally, how do we merge all these signals? For a logged-in user, the sorting priority is strict:

Prediction Score: A personalized prediction of how long the user will spend on the review.
Proximity: How close is the user to the review's location?
Category Matching: Does the review match the user's explicit interests?
Global Popularity: Total time spent by all users on this review.
Recency: Fallback to creation date.

Conclusion

Building the recommendation engine for Claprec was an exercise in balancing complexity with performance. By offloading geo-spatial resolution to helper methods, utilizing a buffer for pagination, and implementing an implicit-feedback Matrix Factorization model, I've created a system is created that feels instant yet deeply personalized.

It's a constant iteration - tuning the weights, adjusting the retraining threshold, and refining how we define "time spent". But for now, it provides a solid technical foundation for the user experience at claprec.dev.

What's Next?

While the recommendation engine serves as the "brain" of the platform, it relies on a robust data skeleton to function. In the next post, Claprec: Database Design - Modeling the Data (5/6), I'll peel back the layers on the storage architecture. I will share the full ER diagram for the project and detail the Entity Framework Core configurations that bring it to life. We'll look at how I modeled the relational database to empower the ML components - designing a schema that ensures data integrity and provides the flexibility needed to feed our algorithms effectively.

I'd love to hear your thoughts on this approach to recommendation systems or answer any questions you might have in the comments below.

Claprec: Frontend - Angular, NgRx, and OpenAPI (3/6)

Kenan Sejmenović — Fri, 15 May 2026 11:37:44 +0000

Series Roadmap

Product Overview (1/6)
Inside the Architecture - N-Tier, decoupling, microservices (2/6)
Frontend - Angular, NgRx, and OpenAPI Integration (3/6)
Machine Learning in Practice (4/6)
Database Design and Data Modeling (5/6)
Engineering Tradeoffs - Limited Time vs. Ideal Architecture (6/6)

Opinionated Structure and DX

Transitioning from a strong background in Next.js and Vue to Angular offered a unique opportunity to contrast distinct architectural philosophies. While Next.js provides an unparalleled Developer Experience (DX) for Server-Side Rendering (SSR), Angular's opinionated structure proves invaluable for enterprise-scale SPAs, preventing the architectural sprawl often seen in less rigid frameworks.

In this third installment of the Claprec series, I dive into the frontend implementation, focusing on the most challenging aspects: managing complex reactive state, handling intricate UI interactions like real-time chat scrolling, and enforcing type safety via Contract-First Design.

Advanced Scroll Management in Real-Time Chat

One of the most significant UX challenges was implementing a real-time chat interface. Default browser rendering behavior during DOM updates can cause unintended scroll shifts: when chat history is loaded, the scroll position is not preserved and snaps to the top, while incoming messages do not trigger automatic scroll to the bottom. To solve this, scroll behavior must be explicitly controlled - preserving the current position during chat history loads, and conditionally snapping to the bottom only when the user is already at the bottom when new messages arrive.

To solve this, I had to deeply leverage Angular's lifecycle hooks and RxJS streams to calculate scroll offsets relative to content height changes.

Key implementation details

Lifecycle Hook: Used ngAfterViewInit to dispatch header/footer dimensions to the store, ensuring the chat container height was calculated correctly before rendering.
Scroll Restoration: Implemented logic to maintain scroll position when prepending history (infinite scroll upwards) vs. snapping to bottom for new messages.

// app.component.ts

public ngAfterViewInit(): void {
  this._store.dispatch(
    setHeaderHeightAction({
      height: this._header.nativeElement.offsetHeight,
    }),
  );

  this._store.dispatch(
    setFooterHeightAction({
      height: this._footer.nativeElement.offsetHeight,
    }),
  );
}

// chat-page.component.ts

protected setChatsAndScroll(chats: DtoPlainChat[], chatType: "INITIAL" | "OLD" | "NEW"): void {
  const oldScrollTop = this._chatSection.nativeElement.scrollTop;
  const oldHeight = this._chatSection.nativeElement.scrollHeight;
  const wasUnscrollable = this._chatSection.nativeElement.scrollHeight
    === this._chatSection.nativeElement.clientHeight;

  this.chats$.next(chats);

  timer(1).subscribe(() => {
    const scrollToBottom = (): void => {
      this._chatSection.nativeElement.scrollTop
        = this._chatSection.nativeElement.scrollHeight
          - this._chatSection.nativeElement.clientHeight;
    };

    const isUnscrollable = this._chatSection.nativeElement.scrollHeight
      === this._chatSection.nativeElement.clientHeight;

    if (chatType === "INITIAL" && isUnscrollable) {
      this.sendChatLoadRequestForMoreChats("INITIAL");

      return;
    }

    if (
      (wasUnscrollable && !isUnscrollable)
      || chatType === "INITIAL"
      || this._scrollState$.getValue() === "BOTTOM"
    ) {
      scrollToBottom();

      return;
    }

    const newHeight = this._chatSection.nativeElement.scrollHeight;
    const newTopScroll = newHeight - oldHeight;

    if (this._scrollState$.getValue() === "MIDDLE") {
      this._chatSection.nativeElement.scrollTop = oldScrollTop;
    }

    if (this._scrollState$.getValue() === "TOP") {
      this._chatSection.nativeElement.scrollTop
      = chatType === "OLD" ? newTopScroll : oldScrollTop;
    }
  });
}

Additionally, handling responsive layouts proved tricky with the window API. Standard window.innerHeight often fails when mobile browser toolbars appear or when using DevTools mobile viewport simulation. I utilized window.visualViewport for accurate height calculations.

// chat-page.component.ts

this._windowHeight$.next(
  window.visualViewport?.height ?? window.innerHeight,
);

Architecting Reusable Pagination & History Management

Pagination is often implemented ad-hoc, leading to boilerplate in every component. To avoid this, I engineered a generic PaginationHelper class. This class encapsulates the complexity of fetching, storing, and synchronizing pagination state with the URL query parameters.

The Challenge

Supporting multiple independent paginators on a single page without state collision.

The Solution

I implemented a PaginationHistory class that maps query parameters to specific paginated responses, ensuring that everything is cached per page. The helper exposes a isPaused setter, allowing specific paginators to ignore URL updates while another paginator is active. This abstraction handles "clean start", context switching, and auto-correction of page numbers.

// paginator.helper.ts

interface IPagination {
  parsedPageNumber: number;
  apiQueryParams: IQueryParam[] | null;
}

interface IPaginationContext<T> {
  items: T[];
  pageNumber: number;
  totalPages: number;
}

class PaginationHistory<T> {
  private _historyMap = new Map<string, IPaginatedResponse<T>[] | null>();

  private getPaginatedResponsesFromHistoryMap(
    apiQueryParams: IQueryParam[] | null,
  ): IPaginatedResponse<T>[] | null | undefined {
    return this._historyMap.get(JSON.stringify(apiQueryParams));
  }

  public getPaginatedResponse(
    pagination: IPagination,
  ): IPaginatedResponse<T> | undefined {
    return this.getPaginatedResponsesFromHistoryMap(
      pagination.apiQueryParams,
    )?.find(
      paginatedResponses =>
        paginatedResponses.metadata?.pageNumber === pagination.parsedPageNumber,
    );
  }

  public setOrAppendPaginatedResponseToHistoryMap(
    apiQueryParams: IQueryParam[] | null,
    paginatedResponse: IPaginatedResponse<T> | null,
  ): void {
    if (!paginatedResponse) {
      this._historyMap.set(
        JSON.stringify(apiQueryParams),
        paginatedResponse,
      );

      return;
    }

    const paginatedResponsesFromHistoryMap
      = this.getPaginatedResponsesFromHistoryMap(apiQueryParams);

    this._historyMap.set(
      JSON.stringify(apiQueryParams),
      paginatedResponsesFromHistoryMap
        ? [
          ...paginatedResponsesFromHistoryMap,
          paginatedResponse,
        ]
        : [paginatedResponse],
    );
  }

  public clearHistoryMap(): void {
    this._historyMap = new Map<string, IPaginatedResponse<T>[]>();
  }
}

export class PaginationHelper<T> {
  private readonly _subscriptionToPagination$
    = new BehaviorSubject<Subscription | null | undefined>(undefined);

  private readonly _isFetching$ = new BehaviorSubject(false);
  private readonly _isClearStateLoading$ = new BehaviorSubject(false);
  private readonly _isCleanStartLoading$ = new BehaviorSubject(false);
  private readonly _isClearContextLoading$ = new BehaviorSubject(false);
  private readonly _isChangeContextLoading$ = new BehaviorSubject(false);

  public readonly isLoading$ = combineLatest([
    this._subscriptionToPagination$,
    this._isFetching$,
    this._isChangeContextLoading$,
    this._isClearContextLoading$,
    this._isClearStateLoading$,
    this._isCleanStartLoading$,
  ]).pipe(
    map(
      ([
        subscriptionToPagination,
        isFetching,
        isChangingContextLoading,
        isClearContextLoading,
        isClearStateLoading,
        isCleanStartLoading,
      ]) => subscriptionToPagination === null
        || subscriptionToPagination === undefined
        || isFetching
        || isChangingContextLoading
        || isClearContextLoading
        || isClearStateLoading
        || isCleanStartLoading,
    ),
  );

  private readonly _isPaused$ = new BehaviorSubject<boolean>(false);

  public set isPaused(isPaused: boolean) {
    this._isPaused$.next(isPaused);
  }

  private readonly _apiQueryParams$
    = new ReplaySubject<IQueryParam[] | null>(1);

  public set apiQueryParams(newApiQueryParams: IQueryParam[] | null) {
    this._apiQueryParams$.next(newApiQueryParams);
  }

  private _paginationContext: IPaginationContext<T> | null | undefined;

  public get paginationContext(): IPaginationContext<T> | null | undefined {
    return this._paginationContext;
  }

  private _pagination: Observable<IPagination>;
  private readonly _paginationHistory = new PaginationHistory<T>();

  constructor(
    private _apiUrl: string,
    public pageSize: number,
    private _router: Router,
    private _snackBar: MatSnackBar,
    private _route: ActivatedRoute,
    private _httpClient: HttpClient,
    private _apiService: ApiService,
  ) {
    this._pagination
      = combineLatest([
        this._route.queryParamMap,
        this._apiQueryParams$,
        this._isPaused$,
      ]).pipe(
        filter(([, , isPaused]) => !isPaused),
        map(([queryParamMap, apiQueryParams]): IPagination => ({
          apiQueryParams,
          parsedPageNumber: parsePageNumberFromQueryParam(
            queryParamMap.get(QUERY_PARAMETERS.PAGE_NUMBER),
          ),
        })),
        distinctUntilChanged(
          (prev, curr) =>
            prev.parsedPageNumber === curr.parsedPageNumber
            && JSON.stringify(prev.apiQueryParams)
            === JSON.stringify(curr.apiQueryParams),
        ),
        startWith(null),
        pairwise(),
        tap(([prev, curr]) => {
          if (!prev) {
            this.handlePagination(curr!);

            return;
          }

          if (
            curr!.parsedPageNumber !== 1
            && JSON.stringify(prev.apiQueryParams)
            !== JSON.stringify(curr!.apiQueryParams)
          ) {
            updateRoutePageNumber(1, _router, _route);

            return;
          }

          this.handlePagination(curr!);
        }),
        map(([, curr]) => curr!),
      );
  }

  public cleanStart(): void {
    this._isCleanStartLoading$.next(true);
    this.clearState();
    this.resetPaginationSubscription();
    this._isCleanStartLoading$.next(false);
  }

  public async handlePageEvent(
    e: PageEvent,
    target: HTMLElement,
  ): Promise<void> {
    const pageNumber = e.pageIndex + 1;

    await updateRoutePageNumber(pageNumber, this._router, this._route);

    target.scrollIntoView({
      behavior: "smooth",
      block: "start",
    });
  }

  private handlePagination(
    pagination: IPagination,
  ): void {
    const paginatedResponse
      = this._paginationHistory.getPaginatedResponse(pagination);

    if (paginatedResponse) {
      this._isFetching$
        .pipe(
          filter(isFetching => !isFetching),
          take(1),
        )
        .subscribe(() => {
          this.changeContext(paginatedResponse);
        });

      return;
    }

    this.fetchNewPaginatedResponse(pagination);
  }

  private fetchNewPaginatedResponse(
    pagination: IPagination,
  ): void {
    this._isFetching$.next(true);

    let params = chainHttpParams([
      API_PAGINATION_QUERY_PARAMS_CALLBACKS.PAGE_SIZE(this.pageSize),
      API_PAGINATION_QUERY_PARAMS_CALLBACKS.PAGE_NUMBER(
        pagination.parsedPageNumber,
      ),
    ]);

    if (pagination.apiQueryParams) {
      params = chainHttpParams(pagination.apiQueryParams, params);
    }

    this._httpClient
      .get<IPaginatedResponse<T>>(
        `${this._apiService.getApiV1Url()}/${this._apiUrl}`,
        {
          params,
          observe: "response",
        },
      )
      .subscribe({
        next: response => {
          if (response.status === HTTP_STATUS_CODE.NO_CONTENT) {
            this._paginationHistory.setOrAppendPaginatedResponseToHistoryMap(
              pagination.apiQueryParams,
              null,
            );

            this.clearContext();

            return;
          }

          const newPaginatedResponse = response.body!;

          const fetchedPageNumber = newPaginatedResponse.metadata!.pageNumber!;

          if (pagination.parsedPageNumber !== fetchedPageNumber) {
            this._paginationHistory.setOrAppendPaginatedResponseToHistoryMap(
              pagination.apiQueryParams,
              newPaginatedResponse,
            );

            updateRoutePageNumber(fetchedPageNumber, this._router, this._route);

            return;
          }

          this._paginationHistory.setOrAppendPaginatedResponseToHistoryMap(
            pagination.apiQueryParams,
            newPaginatedResponse,
          );

          const paginatedResponse
            = this._paginationHistory.getPaginatedResponse(pagination);

          if (!paginatedResponse) {
            throw new Error("Logical error with insertion into map");
          }

          this.changeContext(paginatedResponse);
        },
        complete: () => this._isFetching$.next(false),
        error: httpError => {
          this._isFetching$.next(false);
          openSnackbarForUnexpectedError(this._snackBar, httpError);
        },
      });
  }

  private unsubcribeFromPagination(): void {
    if (!this._subscriptionToPagination$.getValue()) {
      return;
    }

    this._subscriptionToPagination$.getValue()!.unsubscribe();
    this._subscriptionToPagination$.next(null);
  }

  private resetPaginationSubscription(): void {
    this.unsubcribeFromPagination();

    this._subscriptionToPagination$.next(
      this._pagination.subscribe(),
    );
  }

  private clearState(): void {
    this._isClearStateLoading$.next(true);
    this.clearContext();
    this._paginationHistory.clearHistoryMap();
    this._isClearStateLoading$.next(false);
  }

  private clearContext(): void {
    this._isClearContextLoading$.next(true);
    this._paginationContext = null;
    this._isClearContextLoading$.next(false);
  }

  private changeContext(
    paginatedResponse: IPaginatedResponse<T>,
  ): void {
    this._isChangeContextLoading$.next(true);

    this.clearContext();

    this._paginationContext = {
      items: paginatedResponse.data!,
      pageNumber: paginatedResponse.metadata!.pageNumber!,
      totalPages: paginatedResponse.metadata!.totalRecords!,
    };

    this._isChangeContextLoading$.next(false);
  }
}

Recursive State Management with NgRx

Working with paginated recursive data, such as nested comments and replies, means dealing with a dynamic, unbalanced hierarchy where depth and width are unpredictable. Because this structure lacks the ordering or balancing constraints found in optimized trees, operations like search effectively degrade to linear complexity. To streamline the implementation, I flattened the state into an array within the NgRx store. This approach significantly reduces cognitive overhead and simplifies state management, though it introduces a reliance on linear scans to resolve entity relationships.

I defined a ICommentsWrapper interface to manage loading states (areCommentsLoading, areMoreCommentsLoading) and pagination metadata per entity, ensuring the UI remains responsive and data is retained efficiently.

// i-comments.state.ts

import { DtoCustomComment } from "../../../open_api";

export type CommentType =
  Omit<DtoCustomComment, "paginatedReplies"> & {
    isMediaLoading: boolean;
    isCommentLoading: boolean;
  };

export interface ICommentsWrapper {
  forId: string;
  lastPageNumber: number;
  areCommentsLoading: boolean;
  areMoreCommentsLoading: boolean;
  //
  hasMore?: boolean | null;
  comments?: CommentType[] | null;
}

export interface ICommentsState {
  commentsWrappers: ICommentsWrapper[] | null;
}

The Reactive Mindset Shift

Coming from Next.js/Vue, the shift to Angular required a fundamental change in mindset: Imperative -> Declarative.
While "Signals" are the new trend, RxJS Observables remain essential for modeling complex async streams in large systems. NgRx extends the Redux pattern by treating actions as streams, offering immense control over side effects, though with a steeper learning curve and higher boilerplate cost.

Contract-First Design & Type-Safe API Layer

Integrating a .NET backend with an Angular frontend usually risks DTO synchronization issues. I enforced a Contract-First Design using OpenAPI (Swagger).

Implementation

Auto-Generation: DTOs are auto-generated from the backend spec, eliminating manual syncing.
Type-Safe Endpoints: I constructed a centralized API configuration object. This ensures that changing a backend route requires minimal updates in the frontend codebase.

I extended this concept by creating objects that generate callbacks for path and query parameters, ensuring that every API call is strictly typed and validated at compile time.

// http-method.types.ts

export type HttpMethod =
  HTTP_METHOD.GET |
  HTTP_METHOD.PUT |
  HTTP_METHOD.POST |
  HTTP_METHOD.PATCH |
  HTTP_METHOD.DELETE;

export type CommonApiKeys = "GET" | "GET_MORE" | "CREATE" | "EDIT_PART" | "EDIT_WHOLE" | "LIST_PAGINATED" | "LIST_ALL" | "DELETE" | "DELETE_BULK";

// i-api-endpoint.ts

export interface IApiEndpoint<
  TRequestBody = any,
  TResponseBody = any,
  TQueryParams extends
  Record<
    string,
    (value: any) => IQueryParam
  > = Record<string, (value: any) => IQueryParam>,
> {
  path: string | ((...pathParameters: string[]) => string);
  method: HttpMethod;
  queryParams?: Record<"sorting", Record<string, (value: ENUM_SORTING) => IQueryParam[]>> | TQueryParams;
  roles?: Set<ENUM_ROLE>;
  flags?: Set<ENUM_API_FLAGS>;
  builders: IApiEndpointBuilders<TRequestBody, TResponseBody>;
}

export interface IApiEndpointBuilders<
  TRequestBody = any,
  TResponseBody = any,
> {
  createRequestBody: (body: TRequestBody) => TRequestBody;
  createResponseBody: (body: TResponseBody) => TResponseBody;
}

// api-url.helper.ts

export function createSortingQueryParamCallback(queryParam: string):
(value: ENUM_SORTING, order?: number) => IQueryParam[] {
  return function(value: ENUM_SORTING, order?: number): IQueryParam[] {
    return [
      {
        key: `Sorting.${queryParam}.SortingType`,
        value: value.toString(),
      },
      ...(
        order !== undefined
          ? [
            {
              key: `Sorting.${queryParam}.Order`,
              value: order,
            },
          ]
          : []
      ),
    ];
  };
}

export function createQueryParamCallBack<
  T extends string | number | boolean | string[] | number[] | boolean[],
>(queryParam: string): (value: T) => IQueryParam {
  return function(value: T): IQueryParam {
    return {
      key: queryParam,
      value: value,
    };
  };
}

export function chainHttpParams(
  queryParams: IQueryParam[],
  httpParams?: HttpParams,
): HttpParams {
  let actualHttpParams = httpParams ? httpParams : new HttpParams();

  for (const queryParam of queryParams) {
    if (Array.isArray(queryParam.value)) {
      actualHttpParams = actualHttpParams.appendAll({
        [queryParam.key]: queryParam.value,
      });
    }
    else {
      actualHttpParams = actualHttpParams.set(queryParam.key, queryParam.value);
    }
  }

  return actualHttpParams;
}

export function createApiEndpointBuilders<TRequestBody, TResponseBody>(
): IApiEndpointBuilders<TRequestBody, TResponseBody> {
  return {
    createRequestBody: (body: TRequestBody): TRequestBody => body,
    createResponseBody: (body: TResponseBody): TResponseBody => body,
  } satisfies IApiEndpointBuilders<TRequestBody, TResponseBody>;
}

export const withBuilders = <TRequestBody, TResponseBody>():
{
  builders: IApiEndpointBuilders<TRequestBody, TResponseBody>;
} => ({
  builders: createApiEndpointBuilders<TRequestBody, TResponseBody>(),
});

// api-urls.constants.ts

export const API_PAGINATION_QUERY_PARAMS_CALLBACKS = {
  PAGE_SIZE: createQueryParamCallBack<number>(
    API_PAGINATION_QUERY_PARAMS.PAGE_SIZE,
  ),
  PAGE_NUMBER: createQueryParamCallBack<number>(
    API_PAGINATION_QUERY_PARAMS.PAGE_NUMBER,
  ),
  INCLUDE_LINKS: createQueryParamCallBack<boolean>(
    API_PAGINATION_QUERY_PARAMS.INCLUDE_LINKS,
  ),
  INCLUDE_METADATA: createQueryParamCallBack<boolean>(
    API_PAGINATION_QUERY_PARAMS.INCLUDE_METADATA,
  ),
} as const;

export const API = {
  REVIEW: {
    GET: {
      method: HTTP_METHOD.GET,
      path: (reviewId: string) => `review/${reviewId}`,
      flags: new Set([ENUM_API_FLAGS.LOGGED_OPTIONAL]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, DtoRelatedReview>,

    GET_MORE: {
      method: HTTP_METHOD.GET,
      path: (reviewId: string) => `review/more/${reviewId}`,
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, DtoCalculatedReview>,

    CREATE: {
      path: "review",
      method: HTTP_METHOD.POST,
      flags: new Set([ENUM_API_FLAGS.LOGGED]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<InsertDtoReview, DtoPlainReview>,

    EDIT_WHOLE: {
      method: HTTP_METHOD.PUT,
      path: (reviewId: string) => `review/${reviewId}`,
      flags: new Set([
        ENUM_API_FLAGS.LOGGED, ENUM_API_FLAGS.BELONGS_TO_LOGGED_USER,
      ]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<UpdateDtoReview, DtoPlainReview>,

    LIST_PAGINATED: {
      method: HTTP_METHOD.GET,
      path: "review",
      queryParams: {
        PRODUCT_OR_BUSINESS_PARENT_IDS: createQueryParamCallBack<string[]>(
          API_QUERY_PARAMS.PRODUCT_OR_BUSINESS_PARENT_IDS,
        ),
        BUSINESS_ADDRESS_IDS: createQueryParamCallBack<string[]>(
          API_QUERY_PARAMS.BUSINESS_ADDRESS_IDS,
        ),
        RATINGS: createQueryParamCallBack<number[]>(API_QUERY_PARAMS.RATINGS),
        sorting: {
          RATING: createSortingQueryParamCallback(
            API_SORTING_QUERY_PARAMS.RATING,
          ),
          CREATED_AT: createSortingQueryParamCallback(
            API_SORTING_QUERY_PARAMS.CREATED_AT,
          ),
          VIEW_COUNT: createSortingQueryParamCallback(
            API_SORTING_QUERY_PARAMS.VIEW_COUNT,
          ),
        },
        ...API_PAGINATION_QUERY_PARAMS_CALLBACKS,
      },
      ...withBuilders(),
    } as const satisfies IApiEndpoint<
      undefined,
      DtoRelatedReviewPaginatedResponse
    >,

    DELETE: {
      method: HTTP_METHOD.DELETE,
      path: (reviewId: string) => `review/${reviewId}`,
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, undefined>,

    CREATE_MEDIA: {
      method: HTTP_METHOD.POST,
      path: (reviewId: string) => `review/${reviewId}/media`,
      flags: new Set([
        ENUM_API_FLAGS.LOGGED,
        ENUM_API_FLAGS.MULTIPART_FORM_DATA,
      ]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, DtoPlainMedia[]>,

    DELETE_MEDIA: {
      method: HTTP_METHOD.DELETE,
      path: (mediaId: string) => `review/media/${mediaId}`,
      flags: new Set([
        ENUM_API_FLAGS.LOGGED,
        ENUM_API_FLAGS.BELONGS_TO_LOGGED_USER,
      ]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<undefined, undefined>,

    CREATE_VIEW: {
      path: "review/view",
      method: HTTP_METHOD.POST,
      flags: new Set([ENUM_API_FLAGS.LOGGED_OPTIONAL]),
      ...withBuilders(),
    } as const satisfies IApiEndpoint<DtoCustomReviews, undefined>,

    RECOMMENDED: {
      method: HTTP_METHOD.GET,
      path: "review/recommended",
      flags: new Set([ENUM_API_FLAGS.LOGGED_OPTIONAL]),
      queryParams: {
        LAT: createQueryParamCallBack<number>(API_QUERY_PARAMS.LAT),
        LNG: createQueryParamCallBack<number>(API_QUERY_PARAMS.LNG),
        ...API_PAGINATION_QUERY_PARAMS_CALLBACKS,
      },
      ...withBuilders(),
    } as const satisfies IApiEndpoint<
      undefined,
      DtoRelatedReviewPaginatedResponse
    >,
  },
} as const satisfies
Record<string, Partial<Record<CommonApiKeys, IApiEndpoint>>> |
Record<string, Record<string, IApiEndpoint>>;

// write-review-for-product-page.component.ts

// usage (both request and response is strongly typed)

const postBody = {
  rating: this.rating,
  // ...
} as ExtractRequestType<typeof API.REVIEW.CREATE>;

this._httpClient
  .post<ExtractResponseType<typeof API.REVIEW.CREATE>>(
    `${this._apiService.getApiV1Url()}/${API.REVIEW.CREATE.path}`,
    postBody,
  )
  .subscribe({ 
    next: review => {
      // review.reviewId
      // ...
    }
  });

This high-setup-cost approach pays dividends in long-term maintainability and type safety.

Context-Aware Autocomplete Services

Standard autocomplete components are often isolated. However, in complex forms, one input often dictates the dataset of another (e.g., selecting a "City" filters the available "Zipcodes").

I built an autocomplete service architecture that accepts additionalParams via a BehaviorSubject. This allows the service to react to external changes, clear its current cache, and re-fetch data based on the new context. It handles debouncing, prefetching, and pagination internally.

// zipcode-autocomplete.service.ts

interface IAdditionalParams {
  cityId: number | null;
}

@Injectable({
  providedIn: "root",
})
export class ZipcodeAutocompleteService {
  public readonly additionalParams$ = new BehaviorSubject<IAdditionalParams>({
    cityId: null,
  });

  public readonly isLoading$ = new BehaviorSubject<boolean>(false);

  public readonly filteredData$ = new BehaviorSubject<DtoRelatedZipcode[]>([]);

  public readonly nextPageDebounced$ = new Subject<void>();

  public readonly citiesHasZipcodes$
    = new BehaviorSubject<ICityHasZipcodes>({});

  public preselected$ = new Subject<DtoRelatedZipcode>();

  private _prefetced$ = new BehaviorSubject<boolean>(false);

  private readonly _beforeFetchSearchSnapshots:
  IBeforeFetchSearchSnapshot<IAdditionalParams>[] = [];

  private readonly _afterFetchSearchSnapshots:
  IAfterFetchSearchSnapshot<DtoRelatedZipcode, IAdditionalParams>[] = [];

  private readonly _searchQuery$ = new Subject<string>();
  private readonly _fetchDebounce$ = new Subject<string>();

  constructor(
    private _httpClient: HttpClient,
    private _apiService: ApiService,
  ) { 
    // ...
  }

  public search(search: string): void {
    // ...
  }

  public prefetch(): void {
    // ... 
  }

  public preselect(preselectedZipcodeId?: string | null): void {
    // ...
  }

  private observeFetchDebounce(): void {
    // ...
  }

  private observeSearchQuery(): void {
    // ...
  }

  private observeNextPageDebounced(): void {
    // ...
  }

  private determineNextPageNumber(searchQuery: string): number {
    // ...
  }

  private checkIfAlreadyProceededToFetch(
    newBeforeFetchSearchSnapshot: IBeforeFetchSearchSnapshot<IAdditionalParams>,
  ): boolean {
    // ...
  }

  private filterDataBySearchQueryAndAdditionalParams(
    searchQuery: string,
  ): IAfterFetchSearchSnapshot<DtoRelatedZipcode, IAdditionalParams>[] {
    // ...
  }

  private filterData(searchQuery: string): void {
    // ...
  }

  private fetchData(
    searchSnapshotBeforeFetch: IBeforeFetchSearchSnapshot<IAdditionalParams>,
  ): void {
    // ...
  }
}

UI/UX Decisions & Layout Strategy

Angular Material Theming (M2/M3)

Implementing a robust Dark/Light theme toggle using Angular Material was surprisingly difficult. It required deep customization of the M2/M3 theming mixins to ensure contrast consistency across all components.

Intentional Layout Constraints

A deliberate UI decision was made to display content cards in a single column, leaving horizontal space unused.

The Rationale: The application tracks "dwell time" for Machine Learning analysis. Showing multiple entities simultaneously makes it impossible to determine which entity the user is actually viewing. The single-column constraint ensures high-fidelity data for the ML model, prioritizing backend accuracy over frontend real estate usage.

Modular Design

Every UI element, from cards to dialogs and the image cropper, is modular. This ensures consistency and reduces the cognitive load when maintaining the application.

Architectural Note: Client-Side Rendering Strategy

While the version of Angular used in Claprec is fully capable of SSR, I made a strategic decision to keep this application mostly Client-Side Rendered (CSR). This was a deliberate choice to optimize the development process for a demonstration environment:

No SEO Requirement: As the app is not a public marketing site, optimization for search engine crawlers was unnecessary.
Reduced Server Load: Eliminating server-side processing for HTML generation saved significant server resources.
Development Velocity: It simplified the architecture, allowing for faster iteration.

Transitioning the frontend to be SEO-friendly with SSR would be straightforward architecturally, but purposefully sticking to CSR saved time and reduced infrastructure complexity for this specific use case.

What's Next?

With a robust frontend architecture in place - specifically designed to capture high-fidelity user interaction data like dwell time - the stage is set for the intelligence layer of the application.

In the next part, Claprec: Machine Learning in Practice (4/6), the focus will shift from structural engineering to data science. I will discuss how the interaction data captured by the frontend is processed to train models, the specifics of the recommendation algorithms employed, and the challenges of integrating ML pipelines into a .NET environment.

Join me in the next post as we explore the engine that drives Claprec's predictive capabilities.

I'd love to hear your thoughts on these frontend architectural choices or answer any questions you might have in the comments below.

Claprec: Inside the Architecture - N-Tier, decoupling, microservices (2/6)

Kenan Sejmenović — Wed, 13 May 2026 11:49:55 +0000

Series Roadmap

Product Overview (1/6)
Inside the Architecture - N-Tier, decoupling, microservices (2/6)
Frontend - Angular, NgRx, and OpenAPI Integration (3/6)
Machine Learning in Practice (4/6)
Database Design and Data Modeling (5/6)
Engineering Tradeoffs - Limited Time vs. Ideal Architecture (6/6)

System Architecture Overview

The application is deployed within a Dockerized environment consisting of six containers:

3 Backend Microservices: API (the main one), Real-time, and Views-processing.
1 Frontend Container.
Infrastructure: Microsoft SQL Server (MSSQL) and RabbitMQ message broker.

To visualize the backend architecture, the following animation illustrates the layers and some of their dependencies.

This article focuses specifically on the architectural decisions and patterns implemented within the backend microservices.

Main Microservice

The main microservice acts as the primary backend service. It follows an N-Tier Architecture, where the depth of the stack varies based on the complexity of the functionality being implemented.

Architectural Layers

To ensure strict Separation of Concerns (SoC) and adherence to the DRY (Don't Repeat Yourself) principle, the architecture defines three distinct stack depths:

Entity Mutations / CRUD (8 Layers):
Higher CRUD Controller -> Base Higher CRUD Controller -> Service -> Base Higher CRUD Service -> Validation -> BusinessRule -> Base Service -> Repository
Database-Stored Enums (6 Layers):
Db Enum Controller -> Base Db Enum Controller -> Service -> Base Db Enum Service -> Base Service -> Repository
Generic Functionality (4 Layers):
Controller -> Service -> Base Service -> Repository

The "HigherCrud" System: Solving Multiple Inheritance

Entities often share common behaviors: existence checks, validation logic, and standard business rules. Ideally, this would be implemented via multiple inheritance.

However, C# does not support multiple class inheritance, unlike C++.

To compose shared behaviors with a minimal code duplication, I implemented a solution inspired by Unix file permissions (bitwise flags).

The Bitwise Controller Hierarchy

I categorized CRUD operations into "Pure" base controllers, assigning each a specific level (bit value):

Level 0 (ReadBasic): GET paginated list and GET specific entity.
Level 1 (ReadCalculated): Inherits Level 0 + more extensive GET endpoint for calculated properties.
Level 2 (Delete): Inherits Level 0 + DELETE endpoint (includes existence checks).
Level 4 (Create): Inherits Level 0 + POST endpoint (includes validation).
Level 8 (Update): Inherits Level 0 + PATCH endpoint (includes existence checks and validation).

// Level0AbstractHigherCrudController.cs

// Level 0 (Read Basic)

public abstract class Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> :
    AbstractBaseHigherCrudController,
    ILevel0AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel0AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> _baseHigherCrudServiceLevel0;

    protected Level0AbstractHigherCrudController(ILevel0AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> baseHigherCrudServiceLevel0)
    {
        _baseHigherCrudServiceLevel0 = baseHigherCrudServiceLevel0;
    }

    [SwaggerOperation("Level 0", "Get paginated entities")]
    [HttpGet]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status204NoContent)]
    public virtual async Task<ActionResult<PaginatedResponse<TDtoRelated>>> Get([FromQuery] TSearch search)
    {
        return await _baseHigherCrudServiceLevel0.GetPaginated(search, FormReqURLBuilder());
    }

    [SwaggerOperation("Level 0", "Get an entity")]
    [HttpGet(GET_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    public virtual async Task<ActionResult<TDtoRelated>> GetById(TPrimaryKey id)
    {
        return await _baseHigherCrudServiceLevel0.GetById(id);
    }
}

// Level1AbstractHigherCrudController.cs

// Level 1 (Read Calculated)

public abstract class Level1AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel1AbstractHigherCrudController<TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TDtoCalculated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel1AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch> _level1AbstractBaseHigherCrudService;

    protected Level1AbstractHigherCrudController(ILevel1AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TDtoCalculated, TPrimaryKey, TSearch> level1AbstractBaseHigherCrudService)
        : base(level1AbstractBaseHigherCrudService)
    {
        _level1AbstractBaseHigherCrudService = level1AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 1", "Get an entity (detailed)")]
    [HttpGet(GET_CALCULATED_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    public virtual async Task<ActionResult<TDtoCalculated>> GetCalculatedById(TPrimaryKey id)
    {
        return await _level1AbstractBaseHigherCrudService.GetCalculatedById(id);
    }
}

// Level2AbstractHigherCrudController.cs

// Level 2 (Delete)

public abstract class Level2AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel2AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel2AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> _level2AbstractBaseHigherCrudService;

    protected Level2AbstractHigherCrudController(ILevel2AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch> level2AbstractBaseHigherCrudService)
        : base(level2AbstractBaseHigherCrudService)
    {
        _level2AbstractBaseHigherCrudService = level2AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 2", "Delete an entity")]
    [HttpDelete(REMOVE_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    public virtual async Task RemoveById(TPrimaryKey id)
    {
        await _level2AbstractBaseHigherCrudService.RemoveById(id);
    }
}

// Level4AbstractHigherCrudController.cs

// Level 4 (Create)

public abstract class Level4AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert, TInsertValidation> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel4AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel4AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert> _level4AbstractBaseHigherCrudService;

    protected Level4AbstractHigherCrudController(ILevel4AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TInsert> level4AbstractBaseHigherCrudService)
        : base(level4AbstractBaseHigherCrudService)
    {
        _level4AbstractBaseHigherCrudService = level4AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 4", "Create an entity")]
    [HttpPost]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status400BadRequest, Type = typeof(List<DtoValidationError>))]
    [SwaggerResponse(StatusCodes.Status422UnprocessableEntity, "Unprocessable Entity", typeof(List<DtoValidationError>))]
    public virtual async Task<ActionResult<TDtoPlain>> Insert([FromBody] TInsert insert)
    {
        return await _level4AbstractBaseHigherCrudService.Insert(insert);
    }
}

// Level8AbstractHigherCrudController.cs

// Level 8 (Update)

public abstract class Level8AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate, TUpdateValidation> :
    Level0AbstractHigherCrudController<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch>,
    ILevel8AbstractHigherCrudController<TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate>
    where T : class
    where TDtoPlain : class
    where TDtoRelated : TDtoPlain
    where TSearch : BaseSearchDto
{
    private readonly ILevel8AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate> _level8AbstractBaseHigherCrudService;

    protected Level8AbstractHigherCrudController(ILevel8AbstractBaseHigherCrudService<T, TDtoPlain, TDtoRelated, TPrimaryKey, TSearch, TUpdate> level8AbstractBaseHigherCrudService)
        : base(level8AbstractBaseHigherCrudService)
    {
        _level8AbstractBaseHigherCrudService = level8AbstractBaseHigherCrudService;
    }

    [SwaggerOperation("Level 8", "Update an entity")]
    [HttpPatch(UPDATE_BY_ID_ROUTE)]
    [SwaggerResponse(StatusCodes.Status200OK)]
    [SwaggerResponse(StatusCodes.Status400BadRequest, Type = typeof(List<DtoValidationError>))]
    [SwaggerResponse(StatusCodes.Status404NotFound, Type = typeof(DtoError))]
    [SwaggerResponse(StatusCodes.Status422UnprocessableEntity, "Unprocessable Entity", typeof(List<DtoValidationError>))]
    public virtual async Task<ActionResult<TDtoPlain>> UpdateById(TPrimaryKey id, [FromBody] TUpdate update)
    {
        return await _level8AbstractBaseHigherCrudService.UpdateById(id, update);
    }
}

Composing Controllers

Developers can inherit directly from "Pure" controllers for simple endpoints. By summing these values, we create "Mix" controllers that combine functionalities. A specific entity controller simply inherits from the appropriate Mix base class.

Example: An entity requiring ReadBasic (0), Create (4) and Delete (2) functionality inherits from Level 6.
Full CRUD: An entity requiring all operations inherits from Level 15 (0+1+2+4+8).

Implementation Logic

Since C# does not support multiple inheritance, we cannot simply inherit Level2 and Level4 simultaneously to create Level6. Instead, the "Mix" classes pre-chain the inheritance hierarchy to simulate this composition.

For example, Level 13 (Update + Create + Read Calculated + Read Basic) is implemented by inheriting from Level 5, which in turn inherits from Level 1, which inherits from Level 0. This linear chain aggregates the features cumulatively:

Level 0 provides ReadBasic capabilities
Level 1 inherits Level 0 (ReadBasic) and adds ReadCalculated capabilities.
Level 5 inherits Level 1 and adds Create capabilities.
Level 13 inherits Level 5 and adds Update capabilities.

Admittedly, this approach requires pre-defining these specific "Mix" classes in the base library, resulting in a certain degree of code duplication within the foundational layer. However, this is a necessary compromise to bypass the language's constraints. It is a trade-off that pays off significantly in Developer Experience (DX). The result is an elegant and intuitive interface: developers simply inherit from the specific "Level" class they desire, and the complex composition of behaviors is handled automatically.

Service Layer & Extensibility

The Service Layer mirrors the controller hierarchy precisely, ensuring that every "Level" in the API stack has a corresponding logical backbone (Base Higher CRUD Service). This parallel structure handles the validation pipeline, business rules and other concerns.
To ensure flexibility, the architecture relies on polymorphism: core operations are implemented as virtual methods, allowing an override of specific behaviors - such as injecting custom logic before a save - without disrupting the inheritance chain.
Furthermore, if an entity requires functionality outside the standard CRUD scope, the solution is intuitive: simply define a new method in the Controller and a corresponding one in the Service, effortlessly adding the required custom functionality.

Practical Example: "Product" Entity

To implement full CRUD for a "Product" entity:

Inherit HigherBaseCrudController (Level 15).
Inherit HigherBaseCrudService (Level 15).
Define Format and Business Rule Validators.
Define DTOs.

// ProductController.cs

[ApiController]
[Route("")]
public class ProductController :
    Level15AbstractHigherCrudController<Product, DtoPlainProduct, DtoRelatedProduct, DtoCalculatedProduct, long, SearchDtoProduct, InsertDtoProduct, UpdateDtoProduct, IAbstractValidation<InsertDtoProduct>, IAbstractValidation<UpdateDtoProduct>>
{
    private readonly IHigherCrudServiceProduct _higherCrudServiceProduct;

    public ProductController(
        IHigherCrudServiceProduct higherCrudServiceProduct
    ) : base(higherCrudServiceProduct)
    {
        _higherCrudServiceProduct = higherCrudServiceProduct;
    }

    // ...
}

Result: The system scaffolds 6 endpoints automatically (3 GET, 1 POST, 1 DELETE, 1 PATCH).

Validation Pipeline

The validation layer optimizes resource usage by preventing unnecessary database calls.

Format Validator: Checks data constraints (e.g., string length < 255). Returns HTTP 400 on failure.
Business Rule Validator: Checks database constraints (e.g., unique email). Returns HTTP 422 on failure.

Optimization:

If Format Validation fails, the pipeline short-circuits, and Business Rule Validation (DB hit) is skipped.
Business Rule Validation fails fast (returns immediately on first error) to minimize DB load.
Error responses share a unified interface, simplifying frontend error parsing.

// AbstractValidation.cs

public abstract class AbstractValidation<T> : IAbstractValidation<T>
{
    private readonly List<IValidatorWithException<T>> _validators = new();

    public async Task Validate(T t)
    {
        foreach (var validator in _validators)
        {
            var validationResult = await validator.ValidateAsync(t);

            if (!validationResult.IsValid)
            {
                validator.ThrowException(validationResult.Errors);
            }
        }
    }

    protected void AddValidatorsInOrder(params IValidatorWithException<T>[] validators)
    {
        foreach (var validator in validators)
        {
            _validators.Add(validator);
        }
    }
}

// AbstractFormatValidatorWithException.cs

public abstract class AbstractFormatValidatorWithException<T> : AbstractValidator<T>, IFormatValidatorWithException<T>
{
    void IValidatorWithException<T>.ThrowException(List<ValidationFailure> validationFailures)
    {
        throw new ValidationException(validationFailures);
    }
}

// AbstractBusinessRuleValidatorWithException.cs

public abstract class AbstractBusinessRuleValidatorWithException<T> : AbstractValidator<T>, IBusinessRuleValidatorWithException<T>
{
    protected AbstractBusinessRuleValidatorWithException()
    {
        RuleLevelCascadeMode = CascadeMode.Stop;
    }

    void IValidatorWithException<T>.ThrowException(List<ValidationFailure> validationFailures)
    {
        throw new BusinessRuleException(validationFailures);
    }
}

Data Mapping & API Standards

AutoMapper & PATCH Semantics:
Implementing partial updates (PATCH) with AutoMapper presents a challenge: distinguishing between an intentional null update and an ignored field.

Scenario: An entity has an optional description. Updating it to null (to clear it) is indistinguishable from "do not update" if AutoMapper ignores nulls.
Solution: Manual mapping is used for specific edge cases to ensure correctness. Alternatively, switching to PUT (full replacement) solves the ambiguity but increases payload size.

Infrastructure:

Swagger: Configured with versioning and Bearer JWT authentication (including session tracking).
Database Enums: Enums are defined in a dedicated backend layer for seeding, storing byte IDs, and rendering string values (prettified for UI).
SMTP: Email sending is handled by a thread-safe background service (Queue-based) to prevent SMTP failures during concurrent requests.
NSFW filter: Applied to publicly visible media; skipped for private uploads (e.g., identity verification).

Testing & Performance

The backend includes Unit and Integration tests.

Performance Optimization: Integration test execution time was reduced by 91.1% (from 8.3 minutes to 44.2 seconds). A detailed IEEE-format breakdown is available here.

Views-Processing Microservice

This microservice is designed for data analytics and post-processing.

Event-Driven: Listens for view events thrown by the Main microservice via RabbitMQ.
Data Storage: Persists metadata (creation date, user ID, entity ID, IP address etc.) into a dedicated MSSQL database.
Purpose: Aggregates engagement data (views on businesses, products, reviews, comments) for analytical insights.

Real-Time Microservice

Built on SignalR, this microservice manages live connectivity and user presence with a strong focus on resource optimization.

Performance & Resource Management

Memory Footprint: Optimized to utilize 300-350MB of RAM for 5,000+ concurrent users during stress tests.
User Presence: Activity status is stored as a bit flag in the relational database.
Storage: Uses ConcurrentDictionary (static in-memory) for connection management, resolving thread-safety issues encountered with standard dictionaries.

// ChatHub.cs

// user.Id, dictionary of: connectionId, listenToUserId
private static readonly ConcurrentDictionary<long, ConcurrentDictionary<string, long>> _connectedUsersForIndividualChat = new();

Resilience Strategy

Because state is stored in RAM, service failure leads to temporary incoherent IsActive status.

Solution: Rather than implementing complex snapshot persistence, the system relies on the frontend's auto-retry connection strategy. Upon reconnection, the state self-corrects. This trades temporary inconsistency for implementation simplicity and lower overhead.

Bandwidth Optimization

To minimize WebSocket traffic:

Counts vs. Payloads: Only unread notification/chat counts are pushed to clients, not the full objects.
Chat Messages: Messages are only exchanged live when a user explicitly joins a specific chat room.
Queue Management: No message accumulation occurs when a user is disconnected; counts update only upon connection.

Architecture

Repository pattern: Uses Entity Framework via the Repository pattern for data access.
Integration: consumes RabbitMQ events from the main microservice (e.g., new notifications for: replies, reviews etc.).

What's Next

With the backend architecture solidly in place - from N-Tier layers to bitwise CRUD composition - the foundation is set. Next, we'll shift to the client side.

Join me in Claprec: Frontend - Angular, NgRx, and OpenAPI (3/6), where I transition from Next.js to Angular's opinionated structure. We will tackle complex challenges including real-time chat scroll management, architecting reusable pagination, handling recursive state with NgRx, and enforcing type safety via Contract-First Design.

Questions or thoughts on the architecture? Drop a comment - I'd love to hear!

Claprec: Product Overview (1/6)

Kenan Sejmenović — Mon, 11 May 2026 11:36:16 +0000

This post begins a six-part series on Claprec, a review platform engineered to demonstrate scalable system design, complex data modeling, and machine learning integration.

While the surface-level product is a discovery tool for local businesses, the engineering goal was to build a resilient, distributed system capable of handling high-velocity user interactions, recursive data structures, and real-time event propagation.

Series Roadmap

The Core System: Intelligence and Feedback Loops

Claprec is built around a feedback loop pattern. Unlike static directories, this system treats user interactions as first-class citizens that directly influence visibility and ranking.

Visibility is driven by a Machine Learning ranking model. Instead of relying only on simple chronological sorting or basic popularity metrics, the system analyzes engagement signals and behavioral patterns to surface content. This moves the platform toward adaptive, context-aware discovery - a significant architectural challenge compared to standard CRUD apps.

User Capabilities: Modeling Complex Interactions

The platform is user-driven, so I prioritized features that encourage interaction. The focus was on scalable engagement patterns - specifically, how to handle infinite nesting for discussions while keeping queries efficient.

Discovery & Search

Business & Product Discovery: Users can browse robust entities with detailed attributes (hours, contact info, location links, exception dates, etc.). I implemented a filtering engine allowing users to sort by country, city, category, price range, and availability.
Geolocation: The app integrates the Geolocation API to prioritize nearby reviews, with graceful fallbacks for permission denials.

Content Generation & Graph Structures

Recursive Threading: The discussion system supports infinite nesting (Reddit-style). Users can drop comments on reviews, replies to comments, subreplies to replies, ad infinitum. This required implementing recursive structures in the database to handle depth without exploding latency.
Rich Media Reviews: Users can submit reviews with 1-5 star ratings, descriptions, and multiple images.
Reactions Layer: A lightweight engagement system allowing reactions on every node - reviews, comments, replies, and subreplies.

Media & Safety Pipeline

Asset Management: Support for multiple images per entity (reviews, comments, businesses) with view-count tracking for viral detection.
Proactive Moderation: I integrated an automated NSFW filter at the upload layer. It blocks high-risk content before it hits the storage bucket, preventing legal/PR liabilities before they start.

Real-Time Communication

WebSockets: Both the notification system and private chat run over WebSockets. This ensures instant feedback for user actions and real-time messaging without the overhead of polling.
User Controls: Users can manage their profiles (including avatar generation logic for those without photos) and block other users in private chat, balancing safety with open public discourse.

Trust & Verification Flow

To ensure accountability within the ecosystem, I implemented a verification layer. Users can upload identity documents (PDF/Images) to request verified status. Once verified, they unlock the ability to request elevated system roles - a necessary step to prevent bad actors from gaining high-level privileges.

Business Owners: Verification and Entity Management

Business owners get a permissioned slice of the system, centered on a verification workflow to lock down edits. It is a classic Role-Based Access Control (RBAC) pattern designed to prevent the chaos of unchecked distributed edits.

Entity Creation

Owners can model their real-world presence by creating Businesses, Addresses, and Products.

Hierarchical Products: Products can be linked to multiple addresses and have parent-child relationships (e.g., "Lunch Menu" -> "Burgers").
Rich Metadata: Owners manage granular details like working hours, exception dates (for holidays), and feature tags (e.g., "Offers Delivery", "Good for Groups").

Ownership Verification

To claim a business, owners must upload verification documents (PDF/Images) proving their authority. This creates a pending state that requires administrative review before full edit permissions are granted. The system supports multi-owner setups, handling concurrent permissions for a single verified entity.

Specialized Roles: RBAC and Operational Scaling

Claprec leans on a granular Role-Based Access Control (RBAC) system to delegate tasks without bottlenecks. This prevents "privilege creep" and ensures the platform scales operationally.

Bot & Human Scrapers

These roles mirror business owners but are restricted to unclaimed entities.

Note: Bots are granted looser rate limits at the API layer to allow for automated data ingestion, while humans operate under standard throttling constraints.

Moderators

The first line of defense. Their scope includes:

Reviewing reports on user-generated content (reviews, comments, replies).
Deleting content that violates policy.
Managing the moderation queue.

Elevated Moderators

A tier up, handling higher-stakes operations and trust verification:

Reviewing reports on Businesses and Products (deleting content that violates policy).
Approving Business Ownership Claims: Reviewing uploaded documents to verify a user's right to claim a business entity.
User Identity Verification: Validating user-submitted documents to grant "Verified" status.
Deleting users and broadcasting custom notifications (app-wide or email).

Admins

The top-level authority. While Elevated Moderators handle verification, only Admins can authorize role changes.

Role Assignment: Approving or rejecting requests for roles (Scraper, Moderator, Elevated Moderator, Admin) once a user has been verified.
Full spectrum access - the "break glass in case of emergency" role with override capabilities across the entire system.

What's Next

This overview covers the functional scope of Claprec, but the real engineering challenges lie under the hood. In the next post, "Inside the Architecture", we'll look at how I structured the backend to handle these complex relationships and decoupled services.

I'd love to hear your thoughts or questions about the project, so feel free to leave a comment below.

Developing 1st game ever: 9 lessons learned (race game, Unity)

Kenan Sejmenović — Wed, 03 Aug 2022 15:00:40 +0000

First, let me show you a trailer of the game. Don't worry, it's only 1:24 minutes long.

Want to play?

Here is the download link. (in-game hold T to turn on a car)

Disclaimer

It isn't so much of a technical blog, although the whole source code of a game you can find here.
The blog should teach you the lessons a programmer from outside the game-development world learned developing his first game ever.

Beware, it's licensed.

Introduction

It's a 3D race game with advanced manual shifting.
The game was done in less than a month by me and my colleague, and this is my (but also his) first game ever made. The game was made for the competition contest.
A lot of new has been learned, and I think that this blog should give you a few lessons which I learned along making this game.

Technologies used

The game engine is Unity.
Scripting is done using C#.
For the versioning system, I used Git (and Github) of course.

Coming from the web developer world

I've been working mainly on full-stack projects on the web, so this was a new challenge for me.
Coming into the gaming world has been a beautiful experience in which I learned a lot.
It is fascinating to me how the whole system functions in games, and how much knowledge is required to bring entertainment to the gamers.
A lot of the same problems arise in the both web and gaming world, but I noticed that it is a lot easier to hit hardware boundaries accidentally in game development.
A whole new world has been open to me upon learning the cycles in which Unity operates.
Although I don't enjoy gaming that much anymore, I would like to say that this was enlightenment and that I'm impressed.

A word about game engines and Unity

The most interesting to me was the execution order that is run by Unity.
Upon learning that, I had, and still have, a lot of questions - where to put my piece of code so it doesn't bug the whole game down.
I have a lot of questions - about shaders, meshes, and all that magic stuff. Although the game can obviously be made without knowing a lot of the answers (at least in depth that I respect as the "good" answer), I don't feel the satisfaction of knowing all the inner details - how it functions under the hood.
I know that a big part of game engines is based on linear algebra, and although I know the operations - I didn't make my own engine, and I don't think there's a better way to understand a game engine better than to make your own. Making the game engine isn't my priority now, but maybe someday I will try to make my own for fun.
The question could be referenced for a lot of things - you know how to write code but don't know the assembly it resembles, why don't you learn that also? The answer to that maybe lies in the curiosity of the programmer that is reading this - which depth satisfies you?
Anyway, learning the execution order is the crucial thing when working with game engines - and before you realize that upon not being able to optimize a game to a playable level, maybe it is better to learn the execution order beforehand, so you avoid a lot of the headaches.

Challenges (mostly in math)

My part about the game was to make realistic manual shifting. I enjoyed it.
The thing about the manual shifting could be seen in this photo:

(reference: https://www.researchgate.net/figure/Torque-speed-characteristics-of-electric-motors-and-internal-combustion-engines_fig4_317051708).

Force applied to wheels isn't instant (in internal combustion engines, of course), and, as you can see, it is being carried over the line that looks very similar to a sine wave. I have done exactly that in the code, so that part feels realistic. To get that skewness in a line I scaled the angle passed to the sine wave function.
Also, when shifting from e.g. 1st gear to 5th gear - the car should turn off. Torque is being carried between adjacent gears. How I've done that part can be seen below (it's a sketch obviously, but it conveys the message):

Solving heat challenges was also interesting to solve. Feel free to take a look.
It was also interesting to tackle audio problems, which I solved using audio pitch and audio intensity, so it sounds realistic.

A few words about the deadline

The game was done during the semester, so it was stiff and tense with the time. A lot of things could be implemented and fixed, but - time is the final judge. It was done a few days shy of a month with no prior experience in making games.

What went good

Before self-criticism, it's important to acknowledge what went well. So here it is:

I've worked with Git seamlessly, also following the Gitflow concept (more about it here)
math become sooo useful (simulating torque with a sine wave, transforming audio pitch...)
delivered a game that works
got my hands dirty in game development, which I have never planned
tackled a surface of problems with graphics
orientation in 3D space
how torque works in internal combustion engines
how the input system is done in Unity (beautifully btw.)
deeply understood the benefit of separation of configuration from code (e.g. you can change the whole configuration of a car in JSON, even when the game is installed)
stood on the shoulders of a giant - working with free assets provided by the Unity community went unimaginably easy
video editing could be done really fast if you don't have a lot of time left

Recognized mistakes made

Huh.

sometimes audio of an engine doesn't catch up (there's some bug with coroutines)
an opponent car shouldn't be driving in a "God mode" (it was a quick solution though)
the graphics aren't realistic
a better indication that the car is turned off
it's a bit too hard
there should be more obstacles, so it could be more interesting
a car should be able to drift
a car should be able to roll over

9 learned lessons

1. There is a lot to be learned from developing games, even though I don't plan to develop games professionally.

2. Math is hugely usable in game development, I mean a lot.

3. Unity has beautiful, useful tutorials and a big community.

4. It's incredibly easy to meet opportunities to manifest your knowledge about data structures, algorithms, and design patterns in game development because pretty quickly you'll hit performance boundaries, which is nice.

5. Pick a Git strategy or pattern, choose conventions and follow them, you and your team - it's worth it.

6. It's possible to make a game with no prior game-developing experience (although with a few years of programming experience) on a level which is Manual: Desire, or better said - beyond that level, because you have this blog, and I didn't have it.

7. C# is cool (although don't quite know why it has a lot of unneeded syntactic sugar, myb it's better to focus on performance, but anyway - it rocks).

8. Developing a game is a fun challenge.

9. The realization that it's just magic and we're all incredibly lucky to live in a time where you can portray realistic 3D games on a computer that, in the end, only recognizes 0 and 1.

Looking at the game a few months later

It was fun. It could be done wiser. A lot of new has been learned. Saw a completely new world.
I will hit graphics boundaries in another sector of IT, but it's good knowing that a lot of challenges and lessons could be tackled in this field.
Glad that the project was finished just one week off the estimated time, which could be seen as the biggest win.

A word about the beautiful tool - Git

I "learned" Git sometime before, but never had practice with a team.
This was an eye-opening experience, finally, a lot of lessons came into play. I rocked Git only through a console and let me say - it's wonderful.
Knowing how to use Git beyond basic commands is like having magic power at the tips of your fingers, like you obtained a crystal that controls time - or better said: versions.
The next step is to deeply understand Git internals, although I skimmed through internals, there is more to reach, there is more to explore.

Final word

Thanks for reading.
Although it wasn't technical as I like it to be, it was worth writing. A few months passed by, so a lot of technicalities have been forgotten, sorry for that.
Fellow experienced game developers - if you are reading this for whatever reason - leave us your tips below in the comments, we will surely appreciate it.
If you want to - feel free to contribute, with ideas or with the code.

15 Parts of How I Built Food Delivery App, Lessons & Ideas through Laravel and Vue

Kenan Sejmenović — Wed, 07 Oct 2020 18:09:43 +0000

note: I shut down the website

Introduction

There are a lot of apps made for food delivery for big cities, but not a lot of them are made for the small cities.

The article covers how the app is made, its structure, common problems, and solutions.

Why article might be important to you?

Do you plan to make a delivery app, or you want to buy one, or are you interested in starting a delivery app?

Or you want to see how a problem can be solved using the web?

Then, this content is for you.

“Make sure you understand the fundamental principles, i.e., the trunk and big branches, before you get into the leaves/details, or there is nothing for them to hang on to.” - Elon Musk

Here is the app. Take a look.

There is a big chance that the app data will be populated by random users because access to almost every account is open to the public. Please don't populate the application with unrelated stuff. If you cannot log in, try to make a new account.

Link: https://dostava-online.com

User credentials:

Phone number: +387 99/999-999
Email: johndoe@gmail.com
Password: 123123123

Link: https://dostava-online.com/restaurant

Restaurant credentials:

1
- Phone number: +387 22/222-222
- Email: ristus@gmail.com
- Password: 123123123
2
- Phone number: +387 33/333-333
- Email: star@gmail.com
- Password: 123123123

Link: https://dostava-online.com/admin

Admin credentials:

Phone number: +387 11/111-111
Email: dostava.online@gmail.com
Password: 123123123

Overview

on the main page are shown:
- top 3 foods, according to the selling/ratings
- all restaurants sorted according to the sales/ratings/sponsorship/availability
cart for users
additions for foods, free and paid additions
multiple user addresses
delivery/pick up as soon as possible or at the desired time
delivery/pick up food
6 types of notifications for users; order is:
- accepted
- not accepted
- in the making
- in delivery
- delivered
- you can come to pick up the food
ingredients of each dish
one click for the switch of the food availability on the restaurant side
complete CRUD of foods for restaurant
food categories
admin dashboard for sales overview, confirmations, sponsorships

Technical overview

Laravel 6, Vue 2.0, Vuex, Vuetify, Socket.io (Laravel-echo), Node, Redis, MySQL, OAuth 2.0
Webpush notifications implemented for users and restaurants
Slack notifications for admins
Multiauth
Caching of the majority of cachable resources - on back end and front end
Backup 3-5 times/week
Image watermarks
No Laravel mix; advanced webpack configuration
Full tested; ~800 tests (features and unit tests)
Fully extendable and testable structure for algorithms for sorting the top 3 foods on the back end
user/restaurant/admin SPAs separated
HTTP 2.0 for lazy loading Vue components; production raw ~400 files
Fully separated API and front end
Custom artisan commands for production testing
Easily extendable for multiple cities
Easily connectable to the mobile app (separate API made with that in mind)
Mobile-first design

Database plan

Number of tables: 46

Problem: cart items should be seen from all the devices, so saving items in the cookies memory or browser database is not going to help because the user is going to check the cart from the various devices
Solution: complete cart concept is on the back end

Problem: a history of the transactions
Solution: same tables of the cart solution prefixed with finished

Problem: Multiple user addresses (so the user can type in address once and access it anytime with ease)
Solution: home_address on main user table, and user_address table; one-to-many relationship

Problem: cart also should contain paid and free additions
Solution: shopping_cart, shopping_item, shopping_item_free_addition, shopping_item_paid_addition; one-to-many relationships

Problem: duplication of free/paid additions and ingredients
Solution: free/paid additions and ingredients link tables

Problem: some restaurants don't work on the weekends, but all of them work on weekdays on regular
Solution: separate table for weekends with one-to-one relationship

Problem: different delivery prices for the different locations
Solution: default_delivery_price on restaurant table and delivery table; one-to-many relationship

Problem: monthly restaurant fees
Solution: Laravel scheduler empowered with cron

Problem: food categories
Solution: separate table, one-to-many relationship

There are also Telescope tables, OAuth tables, notifications, failed_jobs, migrations, three types of users (user, restaurant, admin)...

Order process

Put items with/without free/paid additions in the cart from the main page/restaurant page
Go to the cart page
Choose if you are coming for the food or desired address for delivery
Choose if delivery/pick up is as soon as possible or at the desired time

After the successful order, the restaurant can either accept or decline the order.

If the 10 minutes pass and the restaurant still didn't accept or decline the order, the user can decline the order.

Declining from the restaurant can happen for various reasons, such as the restaurant forgetting to set unavailability to the dish.

Order process visualisation

Order process diagram, user side:

Order process diagram, restaurant side:

History overview

The history problem is easily solved. After the order is finished, the job is added to the Laravel queue, so its non-blocking.
What job will do is a transfer from the active carts to the finished carts, everything has finished table - cart, items and free/paid additions.

The problem that arises is changing the price of the additions/food in finished orders because finished items/additions are linked to the current info. The solution is to make a serialized snapshot of relevant data at a time. Not implemented in this system yet.

Queues

There are 6 queues required for the application to run correctly (250-350 MB of RAM).

All of them are powered through Redis.

general queue
queue for restaurant notifications
queue for user notifications
queue for admin notifications
queue for processing images

The general queue is at the frontier for the most other queues and for the non-critical data.
Because this application is heavily notification dependent, there are 3 separate queues for the notifications, of which restaurant queue has high priority.

Cron jobs overview

In the background of this application, 6 processes are running alternately.

monthly fee event (calculate restaurants debts)
hourly check which sponsorship is expired
hourly remove old inactive shopping carts
daily clean old backups
daily backup database
weekly backup files

Security

Laravel framework is trying to be as secure as possible.

Every user input is checked both on the client and server-side.

Backup is done daily.

Many barriers to preventing DOS attacks, from the application side and at the OS.

Validations and notifications

Every form is done with a heavy focus on the details.

From the typing incorrect answers to the correct and recommended.

Notifications are done via web-push notifications and in-application notifications. In-application notifications are done using a basic Laravel package that does (almost) a great job.

Data duplication in the database

A lot of the food has the same ingredients, so having a lot of ingredients duplicates does not make any sense.
The same situation is with the paid and free additions.

The solution is to make link tables. So, e.g. multiple dishes can link to the same ingredient, without duplication.

Deactivation

Food, paid/free addition, user, restaurant, admin tables are all soft-deleted, which means that the data will remain in the database, just it won't be shown anywhere like it was deleted. Data remains for analytics, marketing purposes...

Business model

The business model at its core is the same as the Grubhub model. 10% of the order price. A business model based on the value, the best type of business model (subjective).

App profits could be extended by bringing in delivery extension, so the independent delivery man/woman can work and make some cash.

Story

The web application is made for the small cities and the places around the city. Most of the big food delivery companies include the only city and that is the place where this application differs from the others.

The application is a nice startup for the focus on the first city. The structure is easily extendible for multiple cities.

The application was translated from Bosnian into English in a rush. There are some English mistakes.

This is also my second big project, which I did for the 6 months and 21 days, with only 3 days rest. #hustleCulture 🤣

What I learned:

Laravel - in and out
Vue - a lot of it (community, thank you for this gift)
Webpack - headache is the correct translation
MVC - the structure of in-development independent separate parts (if I have to describe it using my words)
SCSS - nice addition to the basic CSS
Real problem of software development: maintaining the same speed of development in a big, robust system where it's so easy to lose the pace; so the only way to go is quality, clean code, implementing defined principles
Redis - fascinating pub-sub; fascinating speed; and the hard thing, not coupled to the Redis strictly, but often related to it - cache invalidation... Nice place to look for logical creativity.
Simple is better
Better spend more time at the planning the database structure than to support bad design weeks/months later
ORM is the nice, fast way to go (didn't have touch with the systems where performance is the real issue, but I assume then the ORM is not the best option)
Ubuntu is easy, understanding the permission system in the multi-user operating system is one of the key concepts to the security (next stage for me is cloud). The scaling problem for the VPS-based solutions is easy to notice, so the huge arise in the cloud makes sense.
Using packages is a messy thing
GraphQL is a way to go in the big APIs, REST will waste so much because of its inflexibility
Developing detailed front end schemes before even deciding which technologies to use on the back end is the way to prevent a lot of the regrets
Writing important code without testing is a crime
PHP is nice and evolving, but at the enterprise always Java/C# is gonna be used
Most of the deaths on this planet in the last 25 years are caused by Javascript. And that's a fact 😂

Thank you for reading. ☄️

Looking for the portfolio inspiration and code? Maybe Vue? 🤫

Kenan Sejmenović — Thu, 24 Sep 2020 16:47:44 +0000

Do you need inspiration for building your portfolio? Grab some inspiration from my project.

Technologies used:

Vue (vue-router)
CSS (flexbox, grids)

Simple, blazing-fast unique portfolio - click here to see it.

Here you can find the source code. 🎯

Mobile-first design.

MIT license - so, feel free to use it.

Lighthouse - every rating over 90. 🚀🚀🚀

Do you want to be a contributor? Here are some ideas for improving the site:

showing bottom tooltips of technologies on the small screens
adding a LinkedIn icon at the top left
a better solution for showing text at About page on different screen sizes
making it PWA (Progressive Web App)
next-gen images format (webp), except for unsupported browsers e.g. Safari

From the previous commits, you can see that it was performing page statistics. The same can be done from automatic web server logging. It was unnecessary, so I removed it.

Thank you for the huge support on my first (previous) post ever. Hope this one will also help you like the previous one.

Weather app in React, Redux, Typescript, and Tailwind

Kenan Sejmenović — Sun, 02 Aug 2020 18:20:01 +0000

Hello reader 👋👋,

In this article, you will learn how to make basic weather app in React, Redux, and Typescript.

The React part is written in Typescript.

The Redux part is written in plain Javascript for the sake of simplicity.

This article is meant for beginners in React. I have about a year's experience in Vue and Vuex before I started learning React and Redux. It's best suited for those readers.

Let me show you the app, then we will mix reverse engineering and going from step one to the final app.

Hope you liked it! If you don't have time to read, here is the source code. 👈

Let's start

Requirements: node.js and npm.

Step 1

Install packages

Let's first execute commands, then I will explain what each command does.

Open your terminal and execute commands:

npx create-react-app weather --template typescript

cd weather

npm install react-icons react-redux react-router-dom redux redux-thunk tailwindcss postcss-cli autoprefixer @fullhuman/postcss-purgecss @types/react-redux @types/react-router-dom

Take a look at why React does not put dependencies in devDependendencies.

The first command builds React template in Typescript. We named our app "weather".

The second command moves us into the application directory.

The third command installs packages:

react-icons - for fancy icons

react-redux - for connecting Redux with React

react-router-dom - for enabling many routes and SPA navigation (SPA - Single Page Application)

redux - for state management

redux-thunk - for enabling asynchronous behavior in redux

tailwindcss - CSS framework for easier styling

postcss-cli - for enabling minifying app for production (CSS file gzipped from ~140kb to ~3kb... WORTH IT 🧐)

autoprefixer - for parsing CSS and adding vendor prefixes to CSS rules

@fullhuman/postcss-purgecss - PostCSS plugin for PurgeCSS

@types/react-redux - type definitions for react-redux (for Typescript)

@types/react-router-dom - type definitions for React Router (for Typescript)

Let's start application:

npm start

Step 2

Remove auto-generated code

Let's remove minimal code that interferes with our goals, for now.

Go into ./src/App.tsx and remove code inside return statement to look like:

return <></>;

At the top you can see:

import logo from "./logo.svg";
import "./App.css";

Remove both imports and delete ./src/App.css.

If you see a white screen on your browser, you are good to go.

For now, it's good. Delete other useless code if you want, but to keep this post shorter, I will cut it here.

Step 3

Building structure

We need to make five new directories inside ./src.

Inside ./src make:

actions
assets
components
pages
reducers

Explanation:

actions - for storing redux actions and action types
assets - for static content, like images
components - it's always a good thing to strive for the Single Responsibility Principle. In a bigger project, you will be able to use the same component multiple times and save time for everyone
pages - a place of clean code and separate concerns where you connect routes to components
reducers - place where dispatched redux actions changes the state of the application

Step 4

Enable Tailwind

Let's add Tailwind to the application.

Open ./src/index.tsx and add:

import "./tailwind.output.css";

Also, add ./tailwind.config.js, so we learn how to add custom properties to Tailwind.

./tailwind.config.js

module.exports = {
  theme: {
    extend: {
      width: {
        "410px": "410px",
      },
    },
  },
};

Before npm start and npm run build we want to build Tailwind also.

To solve this problem, in "scripts" tag in package.json add:

"build:tailwind": "tailwind build src/tailwind.css -o src/tailwind.output.css",
"prestart": "npm run build:tailwind",
"prebuild": "npm run build:tailwind"

Adding "pre" before the start and build, will run the desired command before every npm start and npm run build.

As you can see, there is src/tailwind.css, which is not created yet. So, let's do it.

./src/tailwind.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

Stop watching changes in code by npm by hitting Ctrl + C on Windows in the terminal.

Again, run npm start to compile code. You should now see something like in console:

npm run build:tailwind

And tailwind.output.css should appear in ./src.

Step 5

Prepare Redux

In ./src/reducers make:

./src/reducers/ajaxReducer.js:

const initialState = {
    weather: {},
  };

  export default function (state = initialState, action) {
      switch (action.type) {
          default:
              return state;
      }
  }

We will fetch data from OpenWeatherMap, so we need a place to store data.

Data will be store in the weather, in the state.

For now, let's write the boilerplate code.

./src/reducers/index.js:

import { combineReducers } from "redux";
import ajaxReducer from "./ajaxReducer";

export default combineReducers({
  weatherReducer: ajaxReducer,
});

At index.js combine all the reducers. We have only one - ajaxReducer in this project, but it won't be always the case.

At a large project, having index.js - a central place of Redux reducers is a good thing, "clean code".

Time for action.. actions!

Let's make types.js where we store all types of Redux actions. It's like ./src/reducers/index.js for actions.

In this simple project, we will only have one action.

./src/actions/types.js

export const FETCH_WEATHER = "FETCH_WEATHER";

And, let's make one and only ajax request/redux action. Before that, you need to go to the OpenWeatherMap and make a token.

A token is a requirement for using OpenWeatherMap, that is generous enough to give us a very high number of API calls for free.

./src/actions/ajaxActions.js

import { FETCH_WEATHER } from "./types";

export const fetchWeather = () => async (dispatch) => {
  const ids = {
    Munich: 2867714,
    London: 2643743,
    California: 4350049,
  };

  const fetches = await Promise.all(
    Object.values(ids).map((e) =>
      fetch(
        `https://api.openweathermap.org/data/2.5/forecast?id=${e}&appid=` // here you put your token key
      ).then((e) => e.json())
    )
  );

  dispatch({
    type: FETCH_WEATHER,
    payload: {
      // iterating through object does not guarantee order, so I chose manually
      Munich: fetches[0],
      London: fetches[1],
      California: fetches[2],
    },
  });
};

I chose those cities because I like them. You can pick the cities which you like. Here you can find IDs.

Explanation of ./src/actions/ajaxActions.js:

Import type, so we can connect type with defined action
Make an object of city names and IDs
Store fetched and parsed JSON into constant fetches. Use Promise.all() for fetching data of cities concurrently. URL needs city ID and also Promise.all() expects argument of an array type. Do it by making an array from the object of cities and their ID with Object.values(). Iterate through it with a high-order function map, which returns the array. Fetch does not parse JSON, and it's asynchronous, so first wait for fetching data. Then "unpack" (parse) it by another asynchronous method: JSON. You could use await keyword again, but I prefer then, it seems like beautiful syntax.
In the argument, you can see that we grabbed dispatch, so we can later dispatch an action to the store. If it isn't understandable, read about Javascript closures.
In the end, we call dispatch and pass an object with two keys: type and payload. In type, we link type from ./src/actions/types.js, and in payload, we store data returned from API. There are a lot of ways to not duplicate yourself in this code, but I chose this way for simplicity's sake.

We left ajaxReducer.js unfinished. It's time to complete it.

./src/reducers/ajaxReducer.js

import { FETCH_WEATHER } from "../actions/types";

const initialState = {
  weather: {},
};

export default function (state = initialState, action) {
  switch (action.type) {
    case FETCH_WEATHER:
      return {
        ...state,
        weather: action.payload,
      };
    default:
      return state;
  }
}

As you can see, Redux does not allow us to change just one bit of a state from reducers. First, destructure the current state. Immediately after, overwrite weather key with action payload from ./src/actions/ajaxActions.js.

Step 6

Connect app to redux

Let's first make the main file of Redux. If you worked before with Vuex, you will recognize a pattern here. Vuex and Redux are very similar.

Both have the same purpose, but Vuex is a little easier to understand. Let's name the main Redux file.

./src/store.js

import { createStore, applyMiddleware } from "redux";
import thunk from "redux-thunk";
import rootReducer from "./reducers";

const initialState = {};

const middleware = [thunk];

const store = createStore(
  rootReducer,
  initialState,
  applyMiddleware(...middleware)
);

export default store;

Make it super clean. The code is self-explaining. Clean boilerplate for bigger projects.

In ./src/App.tsx it's time to make some changes.

./src/App.tsx

import React from "react";
import { Provider } from "react-redux";
import store from "./store";
import { BrowserRouter as Router, Switch, Route } from "react-router-dom";

import Home from "./pages/Home";

function App() {
  return (
    <Provider store={store}>
      <Router>
        <Switch>
          <Route path="/" component={Home} />
        </Switch>
      </Router>
    </Provider>
  );
}

export default App;

To make React application work with Redux, we need to wrap the app in , which receives ./src/store.js. It's possible to have multiple stores. Saw it before, but not a big fan //yet 🤣.

You saw a couple of errors in your terminal if you saved your code, I'm sure. It's time to make a first page - Home.

Step 7

Naming assets

For background of cards on home page, I use gifs, so here are names (put whatever gifs you like):

./src/assets/clear.gif

./src/assets/clouds.gif

./src/assets/drizzle.gif

./src/assets/fog.gif

./src/assets/rain.gif

./src/assets/snow.gif

./src/assets/thunderstorm.gif

For Home page eight pictures are used. Four for phones, four for desktops.

For phones:

./src/assets/p_bg1.jpg

...

./src/assets/p_bg4.jpg

For desktops:

./src/assets/d_bg1.jpg

...

./src/assets/d_bg4.jpg

Step 8

Home and its components

./src/pages/Home.tsx

import React, { Component } from "react";

import Card from "../components/home/Card";
import { connect } from "react-redux";
import { fetchWeather } from "../actions/ajaxActions";

interface FormProps {
  fetchWeather: Function;
  weather: Record<string, any>;
}

interface FormState {
  random: number;
  imageSource: string;
}

class Home extends Component<FormProps, FormState> {
  constructor(props: any) {
    super(props);

    const randomInt = (min: number, max: number) =>
      Math.floor(Math.random() * (max - min)) + min; // generate random integer

    this.state = {
      random: randomInt(1, 5), // randomly select background, whose names ends with 1 | 2 | 3 | 4
      imageSource: "",
    };
  }

  // select randomly/change background on click
  setBg = (type: "default" | "click"): void => {
    if (type === "default") {
      this.setState({
        imageSource: require(`../assets/${
          window.innerWidth < 768 ? "p" : "d"
        }_bg${this.state.random}.jpg`),
      });
    } else if (type === "click") {
      // increase random num, then call recursive callback
      if (this.state.random === 4) {
        return this.setState(
          {
            random: 1,
          },
          () => this.setBg("default")
        );
      }

      return this.setState(
        {
          random: this.state.random + 1,
        },
        () => this.setBg("default")
      );
    }
  };

  componentDidMount() {
    this.props.fetchWeather();
    this.setBg("default");
    window.addEventListener("resize", () => this.setBg("default"));
  }

  render() {
    return (
      <div
        className="h-screen w-screen bg-cover bg-center"
        style={{
          backgroundImage: `url(${this.state.imageSource})`,
        }}
        onClick={() => this.setBg("click")}
      >
        <div
          className="flex flex-col justify-center items-center w-screen"
          style={{ height: "95%" }}
        >
          {Object.keys(this.props.weather).map((e, i) => {
            return <Card city={e} key={i} weather={this.props.weather[e]} />;
          })}
        </div>
      </div>
    );
  }
}

const mstp = (state: { weatherReducer: { weather: {} } }) => ({
  weather: state.weatherReducer.weather,
});

export default connect(mstp, { fetchWeather })(Home);

Take advantage of Typescript, by predefining types of component props and state.

Define the component as a class component. The same thing can be done with React Hooks.

The thing to remember at expression setBg is that setState won't immediately set state, so take advantage of its second argument. It receives callback which will execute immediately after the state is updated. And then its time for the recursive call, to change background photo.

The single argument of an arrow function you could write without parentheses. For clarity purposes, let's keep 'em

./src/components/home/Card.tsx

Name your components with a capital letter!

import LeftComponent from "./LeftComponent";
import { Link } from "react-router-dom";
import React from "react";
import { RiMapPinLine } from "react-icons/ri";
import RightComponent from "./RightComponent";
import Tomorrow from "./Tomorrow";
import { determineGif } from "../Utils";

interface FormProps {
  city: string;
  weather: any;
}

function Card(props: FormProps) {
  // find min. and max. temperatures from all timestamps from today
  const findMinAndMaxTemps = (list: any[]): [number, number] => {
    const d = new Date();

    const today = d.getDate() < 10 ? `0${d.getDate()}` : d.getDate();
    let min: number[] = [],
      max: number[] = [];

    list.forEach((e) => {
      if (`${e.dt_txt[8]}${e.dt_txt[9]}` === today.toString()) {
        min.push(e.main.temp_min);
        max.push(e.main.temp_max);
      }
    });

    return [
      Math.round(Math.min(...min) - 273.15),
      Math.round(Math.max(...max) - 273.15),
    ];
  };

  let temperature = 0,
    minTemperature = 0,
    maxTemperature = 0,
    stateOfWeather = "",
    feelsLike = 0,
    speed = 0,
    deg = 0,
    idOfWeather = 0,
    day = true,
    list = [];

  if (props.weather?.list) {
    temperature = Math.round(props.weather.list[0].main.temp - 273.15);
    [minTemperature, maxTemperature] = findMinAndMaxTemps(props.weather.list);
    stateOfWeather = props.weather.list[0].weather[0].main;
    feelsLike = Math.round(props.weather.list[0].main.temp - 273.15);
    speed = props.weather.list[0].wind.speed;
    deg = props.weather.list[0].wind.deg;
    idOfWeather = props.weather.list[0].weather[0].id;
    day = props.weather.list[0].sys.pod === "d";
    list = props.weather.list;
  }

  const [classes, url] = determineGif(idOfWeather);

  return (
    <Link to={`/${props.city}`} className="h-40 w-full sm:w-410px">
      <div className="flex h-40 w-full sm:w-410px">
        <div
          className={`text-white m-2 rounded-lg flex-grow bg-left-bottom ${classes}`}
          style={{
            backgroundImage: `url(${url})`,
          }}
        >
          <div className="flex w-full h-full divide-x divide-gray-400 ">
            <div className="w-9/12">
              <div
                className="mt-2 ml-2 p-2 rounded-lg inline-block text-xs"
                style={{
                  boxShadow: "0 0 15px 1px rgba(0, 0, 0, 0.75)",
                  backdropFilter: "blur(2px)",
                }}
              >
                <div className="flex items-center">
                  <RiMapPinLine />
                  <div className="ml-2">{props.city}</div>
                </div>
              </div>
              <div className="w-full flex justify-around items-center">
                <LeftComponent
                  stateOfWeather={stateOfWeather}
                  idOfWeather={idOfWeather}
                  day={day}
                />
                <div className="flex flex-col text-center">
                  <div className="text-5xl">{temperature}°</div>
                  <div className="text-lg">
                    {minTemperature}/{maxTemperature}°
                  </div>
                </div>
                <RightComponent speed={speed} deg={deg} feelsLike={feelsLike} />
              </div>
            </div>
            <Tomorrow idOfWeather={idOfWeather} day={day} list={list} />
          </div>
        </div>
      </div>
    </Link>
  );
}

export default Card;

If you are curious about determineGif, continue reading, we are almost there!

Take a look at an API response structure, so you can understand variable pairing.

The API response is in Kelvin, so to get Celsius you need to subtract 273.15.

You could do the same thing by passing units=metric at request URL, but its great to meet Javascript floating point number precision.

Remove Math.round() and time will tell you about it 🤣.

As you can see, we get into Tailwind. Tailwind is nice, I would say 'micro' CSS framework, that almost doesn't let you write raw CSS. I don't like it like I do Vuetify, but if you need to manage style at a low and small level, it's great! The thing that I most like about it, it's great documentation.

This component could be separated into smaller parts. But to be time-friendly, I kept it relatively "big".

There are 3 more components, so let's explore 🧐.

./src/components/home/LeftComponent.tsx

import React from "react";
import { determineIcon } from "../Utils";

interface FormProps {
  stateOfWeather: string;
  idOfWeather: number;
  day: boolean;
}

function LeftComponent(props: FormProps) {
  return (
    <div className="flex flex-col text-center">
      {determineIcon(props.idOfWeather, props.day, "h-16 w-16")}
      <div>{props.stateOfWeather}</div>
    </div>
  );
}

export default LeftComponent;

./src/components/home/RightComponent.tsx

import React from "react";

interface FormProps {
  feelsLike: number;
  deg: number;
  speed: number;
}

function RightComponent(props: FormProps) {
  const determineLevel = (temp: number): string[] => {
    if (temp < 10 || temp > 29) {
      return ["Bad", "bg-red-600"];
    }

    if ((temp > 9 && temp < 18) || (temp > 22 && temp < 30)) {
      return ["ok", "bg-yellow-600"];
    }

    if (temp > 17 && temp < 23) {
      return ["Good", "bg-green-600"];
    }

    return [];
  };

  const determineSide = (deg: number): string | undefined => {
    if (deg < 30) return "N";

    if (deg < 60) return "NE";

    if (deg < 120) return "E";

    if (deg < 150) return "ES";

    if (deg < 210) return "S";

    if (deg < 240) return "SW";

    if (deg < 300) return "W";

    if (deg < 330) return "NW";

    if (deg < 360) return "N";
  };

  const feelsLikeProperties = determineLevel(props.feelsLike);

  return (
    <div className="self-end text-center">
      <div
        className={`${feelsLikeProperties[1]} rounded-lg text-xs sm:text-sm p-1`}
      >
        {props.feelsLike} {feelsLikeProperties[0]}
      </div>
      <div className="mt-1 text-xs md:text-sm">
        {determineSide(props.deg)} {Math.round(props.speed * 3.6)} km/h
      </div>
    </div>
  );
}

export default RightComponent;

determineLevel return could be better, but let's keep it simple.

Wind response is in m/s, so to convert it to km/h multiply by 3.6.

determineSide is there for determining if its north, east...

I have a challenge for you - after you make this application, try to make a feature to toggle wind speed between m/s, km/h, and km/s.

./src/components/home/Tomorrow.tsx

import React from "react";
import { RiArrowRightSLine } from "react-icons/ri";
import { determineIcon } from "../Utils";

interface FormProps {
  idOfWeather: number;
  day: boolean;
  list: [];
}

function Tomorrow(props: FormProps) {
  const determineNextDayAbb = (): string => {
    const weekdays = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];

    let date = new Date();
    let index: number;

    if (date.getDay() === 6) {
      index = 0;
    } else {
      index = date.getDay() + 1;
    }

    return weekdays[index];
  };

  const crawlNextDayTemps = (list: any[]): [number, number] | void => {
    const d = new Date();
    d.setDate(d.getDate() + 1); // tomorrow

    const tomorrow = d.getDate() < 10 ? `0${d.getDate()}` : d.getDate();

    let min: number[] = [],
      max: number[] = [];

    list.forEach((e) => {
      if (`${e["dt_txt"][8]}${e["dt_txt"][9]}` === tomorrow.toString()) {
        min.push(e.main.temp_min);
        max.push(e.main.temp_max);
      }
    });

    return [
      Math.round(Math.min(...min) - 273.15),
      Math.round(Math.max(...max) - 273.15),
    ];
  };

  const nextDayTemps = crawlNextDayTemps(props.list);

  return (
    <div className="w-3/12">
      <div className="flex justify-between p-2">
        <div className="text-xs">{determineNextDayAbb()}</div>
        <div className="text-xs flex items-center">
          <div>More</div>
          <RiArrowRightSLine />
        </div>
      </div>
      <div className="flex flex-col text-center">
        <div className="w-full">
          {determineIcon(props.idOfWeather, props.day, "h-16 w-16 mx-auto")}
        </div>
        <div className="text-lg">
          {Array.isArray(nextDayTemps) ? nextDayTemps[0] : "?"}/
          {Array.isArray(nextDayTemps) ? nextDayTemps[1] : "?"}°
        </div>
      </div>
    </div>
  );
}

export default Tomorrow;

Expression names are self-explaining. The classical example of a functional component.

Step 9

City and its components

It's a pretty long article. A lot longer than I expected to 😅.
Let's first add the city route to React.

./src/App.tsx

Before

<Route path="/" component={Home} />

add:

<Route path="/:city" component={City} />

Add the "City" route before the "Home" route, or take advantage of exact prop.

At the top of ./src/App.tsx add:

import City from "./pages/City";

./src/pages/City.tsx

import React, { Component } from "react";

import Desktop from "../components/city/Desktop";
import { connect } from "react-redux";
import { fetchWeather } from "../actions/ajaxActions";

// match.params.city is URL (react-router) variable
interface FormProps {
  fetchWeather: Function;
  match: {
    params: {
      city: string;
    };
  };
  weather: Record<string, any>;
}

interface FormState {
  imageSrc: string;
  random: number;
}

class City extends Component<FormProps, FormState> {
  constructor(props: any) {
    super(props);

    if (
      this.props.match.params.city !== "Munich" &&
      this.props.match.params.city !== "London" &&
      this.props.match.params.city !== "California"
    ) {
      window.location.replace("/404");
      return;
    }

    if (!Object.keys(this.props.weather).length) {
      // fetch from api, if city is accessed directly
      this.props.fetchWeather();
    }

    const randomInt = (min: number, max: number) =>
      Math.floor(Math.random() * (max - min)) + min;

    this.state = {
      imageSrc: "",
      random: randomInt(1, 3), // choose random photo from 2 available photos
    };
  }

  updateDimensions = () => {
    // change background photo for phone/desktop
    this.setState({
      imageSrc: require(`../assets/${
        window.innerWidth < 768 ? "p" : "d"
      }_${this.props.match.params.city.toLowerCase()}${this.state.random}.jpg`),
    });
  };

  componentDidMount() {
    this.updateDimensions();
    window.addEventListener("resize", this.updateDimensions);
  }

  render() {
    return (
      <div
        className="h-screen w-screen bg-cover bg-center"
        style={{
          backgroundImage: `url(${this.state.imageSrc})`,
        }}
      >
        <Desktop
          city={this.props.match.params.city}
          info={this.props.weather[this.props.match.params.city]}
        />
      </div>
    );
  }
}

const mstp = (state: { weatherReducer: { weather: {} } }) => ({
  weather: state.weatherReducer.weather,
});

export default connect(mstp, { fetchWeather })(City);

As you can see, if the URL is not these 3 cities, we redirect the user to the 404 pages. Challenge here for you is to make a good-looking 404 page.

The same pattern for changing background photo is used here.

In case the user enters URL directly, the application fetches data from API if there's no data in the state.

Here is the elephant of the code 😅

./src/components/city/Desktop.tsx

import React, { useState } from "react";
import { WiHumidity, WiStrongWind } from "react-icons/wi";

import { GiCrossedAirFlows } from "react-icons/gi";
import { MdVisibility } from "react-icons/md";
import { determineIcon } from "../Utils";

interface FormProps {
  city: string;
  info: any;
}

function Desktop(props: FormProps) {
  const [day, setDay] = useState(0);
  const [hour, setHour] = useState(0);

  const blurredChip = {
    boxShadow: "0 3px 5px rgba(0, 0, 0, 0.3)",
    backdropFilter: "blur(2px)",
  };

  const determineNext5Days = (): string[] => {
    const days = [
      "Sunday",
      "Monday",
      "Tuesday",
      "Wednesday",
      "Thursday",
      "Friday",
      "Saturday",
    ];

    let next5Days = [];

    for (let i = 0; i < 4; i++) {
      const d = new Date();
      d.setDate(d.getDate() + i);

      next5Days.push(days[d.getDay()]);
    }

    return next5Days;
  };

  interface Simplified {
    time: string;
    temp: number;
    feelsLike: number;
    weatherID: number;
    weatherState: string;
    day: boolean;
    humidity: number;
    pressure: number;
    windSpeed: number;
    visibility: number;
  }

  // pluck relevant info of todays timestamps
  const determineTimestamps = (day: number, list: any[]): any[] => {
    const d = new Date();
    d.setDate(d.getDate() + day);

    const timestamps: Simplified[] = [];

    for (const e of list) {
      if (parseInt(`${e["dt_txt"][8]}${e["dt_txt"][9]}`) === d.getDate()) {
        timestamps.push({
          time: e.dt_txt.slice(11, 16),
          temp: Math.round(e.main.temp - 273.15),
          feelsLike: Math.round(e.main.feels_like - 273.15),
          weatherID: e.weather[0].id,
          weatherState: e.weather[0].main,
          day: e.sys.pod === "d",
          humidity: e.main.humidity,
          pressure: e.main.pressure,
          windSpeed: Math.round(e.wind.speed * 3.6),
          visibility: Math.round(e.visibility / 100),
        });
      }
    }

    return timestamps;
  };

  // rather return the last timestamps than earlier ones (e.g. 21:00 > 03:00)
  const checkTerrain = (squares: number, tss: Simplified[]) => {
    let cut: any[] = [];

    const numberOfNeededRemoval = tss.length - squares;

    if (numberOfNeededRemoval < 0) return tss;

    for (let i = numberOfNeededRemoval; i < tss.length; i++) {
      cut.push(tss[i]);
    }

    return cut;
  };

  const adaptToWidth = (tss: Simplified[]) => {
    // show minimum four squares of timestamps to max 8
    if (tss.length < 5) return tss;

    if (window.innerWidth < 950) {
      return checkTerrain(4, tss);
    } else if (window.innerWidth < 1150) {
      return checkTerrain(5, tss);
    } else if (window.innerWidth < 1250) {
      return checkTerrain(6, tss);
    } else if (window.innerWidth < 1350) {
      return checkTerrain(7, tss);
    }

    return checkTerrain(8, tss);
  };

  // until info from api is fetched
  const timestamps = props.info?.list
    ? adaptToWidth(determineTimestamps(day, props.info?.list))
    : [];

  if (!timestamps.length) {
    return <></>;
  }

  // after fetch
  return (
    <>
      <div className="w-screen flex justify-between" style={{ height: "65%" }}>
        <div className="text-white pt-8 pl-8">
          <div className="text-6xl">
            {determineIcon(timestamps[hour].weatherID, timestamps[hour].day)}
          </div>
          <div className="text-4xl my-1 sm:my-0">
            {timestamps[hour].weatherState}
          </div>
          <div className="text-xl my-1 sm:my-0">{props.city}</div>
          <div className="text-5xl font-bold">{timestamps[hour].temp}°C</div>
        </div>
        <div className="mt-20 mr-4 md:mr-20">
          <div className="flex">
            <div className="text-gray-200 pr-1">
              <WiHumidity className="text-3xl" />
            </div>
            <div>
              <div className="text-gray-200 text-sm sm:base">Humidity</div>
              <div className="text-white text-2xl sm:text-3xl font-bold">
                {timestamps[hour].humidity}%
              </div>
            </div>
          </div>

          <div className="flex my-4">
            <div className="text-gray-200 pr-1">
              <GiCrossedAirFlows className="text-2xl" />
            </div>
            <div>
              <div className="text-gray-200 text-sm sm:base">Air Pressure</div>
              <div className="text-white text-2xl sm:text-3xl font-bold">
                {timestamps[hour].pressure} hPa
              </div>
            </div>
          </div>

          <div className="flex my-4">
            <div className="text-gray-200 pr-1">
              <WiStrongWind className="text-2xl" />
            </div>
            <div>
              <div className="text-gray-200 text-sm sm:base">Wind speed</div>
              <div className="text-white text-2xl sm:text-3xl font-bold">
                {timestamps[hour].windSpeed} km/h
              </div>
            </div>
          </div>

          <div className="flex my-4">
            <div className="text-gray-200 pr-1">
              <MdVisibility className="text-2xl" />
            </div>
            <div>
              <div className="text-gray-200 text-sm sm:base">Visibility</div>
              <div className="text-white text-2xl sm:text-3xl font-bold">
                {timestamps[hour].visibility}%
              </div>
            </div>
          </div>
        </div>
      </div>

      <div className="w-screen text-white" style={{ height: "35%" }}>
        <div className="flex items-center pl-2 sm:pl-8">
          {determineNext5Days().map((e, i) => {
            return (
              <div
                className="px-2 py-1 mx-2 lg:mb-2 rounded-lg cursor-pointer"
                style={day === i ? blurredChip : {}}
                onClick={() => {
                  setHour(0);
                  setDay(i);
                }}
                key={i}
              >
                {e}
              </div>
            );
          })}
        </div>

        <div className="flex justify-around px-8 pt-6 sm:pt-5">
          {timestamps.map((e: any, index: number) => {
            return (
              <div
                key={index}
                className="h-40 w-40 flex flex-col cursor-pointer"
                style={{
                  boxShadow: "0 0 15px 1px rgba(0, 0, 0, 0.75)",
                  backdropFilter: "blur(2px)",
                  transform: hour === index ? "scale(1.1)" : "",
                  zIndex: hour === index ? 2 : 1,
                }}
                onClick={() => setHour(index)}
              >
                <div className="pt-2 pl-2">{e.time}</div>
                <div className="flex-grow"></div>
                <div className="pl-1 sm:pl-2 pb-1 sm:pb-2">
                  <div className="text-2xl font-bold">{e.temp}°C</div>
                  {hour === index ? (
                    <div className="text-xs sm:text-base">
                      Feels like {e.feelsLike}°
                    </div>
                  ) : null}
                </div>
              </div>
            );
          })}
        </div>
      </div>
    </>
  );
}

export default Desktop;

Challenge for you can be to separate this huge chunk of code into smaller components.

Welcome to React Hook. The hooks are amazing. I was wondering why the dev community makes all this drama about hooks. I didn't know anything about React back then. But after learning, I realised that it's a nice developer experience.

Here is the power of Javascript - callbacks.

Challenge for you could be to show the time of these cities. They are not in the same timezone, so its gonna be interesting.

Life without high-order functions would be painful.

Step 10

Utils.tsx

There is a lot of functionality that needs to be shared between components. Don't clutter code with duplications.

The functionality that we will adapt according to API is changing icons and gifs.

It's hardcoded. If the project was real-life, it will be through RegEx and loops. But for this purpose, the switch will do the job.

To not clutter already long post, here is the code of Utils.tsx. Path: ./src/components/Utils.tsx

Step 11

Prepare for production

./postcss.config.js

const purgecss = require("@fullhuman/postcss-purgecss")({
  content: [
    "./src/**/*.html",
    "./src/**/*.ts",
    "./src/**/*.tsx",
    "./public/index.html",
  ],

  defaultExtractor: (content) => {
    const broadMatches = content.match(/[^<>"'`\s]*[^<>"'`\s:]/g) || [];

    const innerMatches = content.match(/[^<>"'`\s.()]*[^<>"'`\s.():]/g) || [];

    return broadMatches.concat(innerMatches);
  },
});

const cssnano = require("cssnano");

module.exports = {
  plugins: [
    require("tailwindcss"),
    require("autoprefixer"),
    cssnano({
      preset: "default",
    }),
    purgecss,
  ],
};

./package.json

"build:tailwind": "tailwind build src/tailwind.css -o src/tailwind.output.css"

change to

"build:tailwind": "postcss src/tailwind.css -o src/tailwind.output.css"

Run npm run build and you will get rid of the unused Tailwind classes and end up with ~3kb CSS file.

There's an option for passing ENV argument into npm build and minimizing CSS only for production, but let's keep it simple here.

You may serve production build with the static server. You should receive a manual in the terminal after npm run build.

Voila!

Backstory

Why I built this application?

To get a taste of React, Redux, Typescript, and Tailwind. I've learned those in 3 days.

Why Redux in the ultra-small application?

To find out why the whole Internet complains about Redux... but it's not that scary!

Why bother posting it?

Someone is gonna find it useful. More content - better.

Can't wait to learn more about these web technologies. 🧐

The end

I hope you learned something from my first post. I thought that post would be much shorter. Even in a simple application is hard to cover all parts.

Thank you for reading. I hope I helped you. A well thought out critique is welcome.