From 1b38f250e5049f62d7c395d30356d3120357ec12 Mon Sep 17 00:00:00 2001
From: AryanGh-imp <aryan.ghasemi.imp@gmail.com>
Date: Wed, 3 Jun 2026 16:45:39 +0330
Subject: [PATCH] docs: add detailed README for Advanced Multithreading banking
 system assignment

---
 README.md | 256 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 255 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index aab0919..39f2085 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,256 @@
-# HW-09-Advanced-Multithreading
+# HW-09 — Advanced Multithreading
+
+---
+
+## Theoretical Questions 📝
+
+## TODO
+
+---
+## Practical Assignment 💻
+
+## 🏦 Advanced Banking & Transaction Processing System
+
+---
+
+### 🧭 Overview
+
+Modern banking systems process thousands of transactions concurrently. Multiple worker threads may read account data, update balances, or transfer money between accounts simultaneously.
+
+In this assignment, you will implement the **concurrency control layer** of a banking system. The goal is to ensure:
+
+* Correctness under concurrent execution
+* Absence of race conditions
+* Deadlock-free transfers
+* Reasonable concurrency performance
+
+---
+
+### 📦 Provided Components (IMPORTANT)
+
+The following parts of the system are already implemented and **must NOT be modified**:
+
+#### ✅ Fully implemented:
+
+* Transaction stream parsing
+* Transaction generation / loading
+* ExecutorService (thread pool) setup
+* Worker thread management
+* System startup and execution flow
+* Live monitoring / balance visualization
+* JUnit test suite
+
+---
+
+### ❗ Your Responsibility
+
+You are ONLY responsible for implementing thread-safe logic inside:
+
+#### 📄 `BankAccount.java`
+
+You must implement the following methods:
+
+```java
+deposit(int amount)
+withdraw(int amount)
+transfer(BankAccount target, int amount)
+getBalance()
+```
+
+---
+
+### 🏗 System Architecture
+
+```
+                  Transaction Stream
+                           │
+                           ▼
+                  ExecutorService Pool
+                           │
+        ┌──────────────────┼──────────────────┐
+        ▼                  ▼                  ▼
+   Worker A           Worker B           Worker C
+        │                  │                  │
+        └──────────────────┼──────────────────┘
+                           ▼
+                    Shared Bank Accounts
+```
+
+Multiple worker threads may access the same accounts concurrently.
+
+Execution order is **non-deterministic**, and correctness must be guaranteed regardless of scheduling.
+
+---
+
+### 🧠 Core Requirement
+
+Your implementation must ensure:
+
+* Shared state consistency
+* Thread safety
+* No lost updates
+* Correct final balances regardless of thread execution order
+
+---
+
+## 🛠 Implementation Requirements
+
+---
+
+### 🟢 Phase 1 — Thread-Safe Account Operations
+
+Implement safe concurrent access for:
+
+* deposit
+* withdraw
+* getBalance
+
+#### Requirements:
+
+* No lost updates
+* No corrupted balances
+* Multiple threads may safely access different accounts concurrently
+* `getBalance()` must always return a valid state
+
+---
+
+### 🔵 Phase 2 — Atomic Transfers
+
+Implement:
+
+```java
+transfer(BankAccount target, int amount)
+```
+
+#### Requirements:
+
+* Transfer must be **atomic**
+* Money must never be created or lost
+* Partial updates are NOT allowed
+* Concurrent transfers must not corrupt balances
+
+Example of invalid behavior:
+
+```
+A → B transfer starts
+A is debited
+Crash / thread switch happens
+B is never credited ❌
+```
+
+---
+
+### 🔴 Phase 3 — Deadlock Prevention
+
+Transfers involve TWO accounts, which introduces risk of deadlock.
+
+Example:
+
+```
+Thread 1: A → B
+Thread 2: B → A
+```
+
+If locks are acquired incorrectly, the system may freeze.
+
+#### Requirements:
+
+* System must be completely deadlock-free
+* Must pass stress tests with high concurrency
+* Must work under arbitrary transaction ordering
+
+---
+
+### ⚙ Allowed Java Concurrency Tools
+
+You may use:
+
+* `synchronized`
+* `ReentrantLock`
+* `ReentrantReadWriteLock`
+* `Condition`
+* `Atomic classes`
+* `java.util.concurrent` utilities
+
+---
+
+### ❌ Not Allowed
+
+* Busy waiting (e.g., `while(true)`)
+* Modifying test files
+* Modifying method signatures
+* Creating additional worker threads
+* Changing system architecture outside `BankAccount`
+
+---
+
+### 📊 Live Monitoring (Debug Tool)
+
+The system includes a live balance visualization tool.
+
+It shows:
+
+* Real-time account balances
+* Effects of concurrent transactions
+* Potential race conditions
+
+⚠ This tool is NOT part of grading.
+
+---
+
+### 🧪 Testing
+
+A full JUnit test suite is provided.
+
+Your solution will be evaluated on:
+
+---
+
+#### ✅ Correctness
+
+* No race conditions
+* No lost updates
+* Correct final balances
+
+---
+
+#### 🧨 Robustness
+
+* No deadlocks under stress tests
+* Stable execution under high concurrency
+* Correct behavior under random transaction ordering
+
+---
+
+#### ⚡ Performance
+
+* Independent accounts should not block each other unnecessarily
+* Avoid global locking unless absolutely necessary
+* System should scale with number of threads
+
+---
+
+### 🌟 Bonus Challenge (Optional)
+
+Implement conditional waiting for insufficient funds:
+
+* Withdraw should wait if balance is insufficient
+* Transfer should wait until funds are available
+
+#### Requirements:
+
+* No busy waiting
+* No CPU spinning
+* No starvation
+
+---
+
+### 💡 Hint
+
+Start with correctness first.
+
+Then optimize concurrency.
+
+A simple correct solution is always better than a fast incorrect one.
+