English · Srpski

---

EN - Technical Documentation

ChaoticCupid is a real-time matchmaking simulation system built on .NET 8. It demonstrates modern distributed application patterns - asynchronous communication, background processing, and thread-safe state management - through a PubSub architecture powered by ASP.NET Core SignalR.

System Architecture

The project follows a decoupled client-server model using WebSockets for low-latency, bi-directional communication.

ChaoticCupid.Server

The backbone of the system, responsible for orchestration and business logic:

• Registry Management - a centralized, thread-safe PersonRegistry tracks all active users
• SignalR Hub - CupidHub manages connection lifecycle and exposes the client-facing interface
• Background Orchestrator - CupidService runs independently of the request cycle, executing matchmaking every 60 seconds

ChaoticCupid.Client

A terminal-based interface built for clarity:

• Rich UI - powered by Spectre.Console with colored panels, styled prompts, and a FigletText banner
• Command Input - custom keystroke handler with tab-completion for /block
• State Management - tracks pending letter confirmation and blocked users locally

Technical Implementation

Thread-Safe State

PersonRegistry uses manual lock blocks to prevent race conditions during concurrent registrations and disconnections, ensuring data integrity throughout the matchmaking cycle.

Matchmaking Algorithm

Candidates are scored against each recipient using a weighted system:

Factor	Points
Same city	+30
Age within ±2 years	+20
Cryptographic random factor	+0 to 100

The candidate with the highest score becomes the letter sender. The random element is generated via RandomNumberGenerator (System.Security.Cryptography) - the modern equivalent of RNGCryptoServiceProvider.

Connection Resilience

• On startup, the client retries every 3 seconds until the server responds
• If the server drops during a session, a Closed event notifies the user to restart
• Automatic reconnect is intentionally disabled - the server holds state in memory and would not recognize a reconnected client

---

SR - Dokumentacija

ChaoticCupid je sistem za simulaciju provodadžisanja u realnom vremenu, izgrađen na .NET 8 platformi. Projekat demonstrira moderne obrasce distribuiranih aplikacija - asinhronu komunikaciju, pozadinsku obradu i bezbedno upravljanje stanjem u višenitnom okruženju - kroz PubSub arhitekturu zasnovanu na ASP.NET Core SignalR-u.

Arhitektura Sistema

Projekat koristi razdvojenu klijent-server arhitekturu uz WebSocket konekciju za dvosmernu komunikaciju sa niskim kašnjenjem.

ChaoticCupid.Server

Okosnica sistema zadužena za orkestraciju i poslovnu logiku:

• Upravljanje Registrom - centralizovani, thread-safe PersonRegistry prati sve aktivne korisnike
• SignalR Hub - CupidHub upravlja životnim ciklusom konekcija i pruža interfejs za klijente
• Pozadinski Orkestrator - CupidService radi nezavisno od request ciklusa i izvršava mečovanje svakih 60 sekundi

ChaoticCupid.Client

Terminalni interfejs izgrađen za jasnoću i upotrebljivost:

• Bogati UI - Spectre.Console sa obojenim panelima, stilizovanim promptovima i FigletText bannerom
• Unos Komandi - prilagođeni hendler sa tab-completion podrškom za /block
• Praćenje Stanja - lokalno upravljanje potvrdom pisama i listom blokiranih korisnika

Tehnička Implementacija

Bezbednost Niti

PersonRegistry koristi lock blokove za sprečavanje race condition situacija tokom istovremenih registracija i diskonekcija, čuvajući integritet podataka tokom celog ciklusa mečovanja.

Algoritam Mečovanja

Kandidati se boduju u odnosu na svakog primaoca prema sledećem sistemu:

Faktor	Poeni
Isti grad	+30
Godište u rasponu ±2	+20
Kriptografski nasumični faktor	+0 do 100

Kandidat sa najvišim skorom postaje pošiljalac pisma. Nasumični element generiše RandomNumberGenerator (System.Security.Cryptography) - moderna zamena za RNGCryptoServiceProvider.

Otpornost Konekcije

• Pri pokretanju, klijent pokušava konekciju svakih 3 sekunde dok server ne odgovori
• Ako server padne tokom sesije, Closed event obaveštava korisnika da ponovo pokrene aplikaciju
• Automatski reconnect je namerno isključen - server čuva stanje u memoriji i ne bi prepoznao ponovo konektovanog klijenta

---

Getting Started / Pokretanje

Prerequisites / Preduslovi

• .NET 8.0 SDK

Setup / Uputstvo

1. Clone the repository / Kloniraj repozitorijum

git clone git@github.com:ljubogdan/chaotic-cupid.git
cd chaotic-cupid

2. Launch the server / Pokreni server

dotnet run --project ChaoticCupid.Server

Server listens on http://localhost:5104.

3. Launch a client / Pokreni klijent

dotnet run --project ChaoticCupid.Client

Each client runs in a separate terminal window.