GuilanCE/internet-engineering-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(presentation): localize slides and fix diagrams

Browse Source
This commit is contained in:
Amirhossein Khalili
2026-06-16 14:37:09 +03:30
parent 5281f73e0a
commit 0f402d68f7
6 changed files with 115 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/images/chatroom-architecture.svg
View File

@@ -3,7 +3,7 @@
<desc id="desc">A minimal architecture diagram showing browser clients, FastAPI WebSocket endpoint, room manager, and room broadcasts.</desc> <desc id="desc">A minimal architecture diagram showing browser clients, FastAPI WebSocket endpoint, room manager, and room broadcasts.</desc>
<rect width="960" height="540" fill="#f7f9fc"/> <rect width="960" height="540" fill="#f7f9fc"/>
<text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">Project Architecture</text> <text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">Project Architecture</text>
<text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="17">Each browser keeps one WebSocket connection. The server broadcasts only inside the selected room.</text> <text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="16">Each browser keeps one WebSocket connection. The server broadcasts only inside the selected room.</text>
<g font-family="Inter, Arial, sans-serif"> <g font-family="Inter, Arial, sans-serif">
<rect x="82" y="168" width="188" height="76" rx="14" fill="#ffffff" stroke="#d0d5dd"/> <rect x="82" y="168" width="188" height="76" rx="14" fill="#ffffff" stroke="#d0d5dd"/>
<text x="126" y="200" fill="#101828" font-size="18" font-weight="700">Client A</text> <text x="126" y="200" fill="#101828" font-size="18" font-weight="700">Client A</text>
@@ -25,8 +25,8 @@
<path d="M270 334 C318 334 330 310 376 310" fill="none" stroke="#2563eb" stroke-width="4" marker-end="url(#arrow)"/> <path d="M270 334 C318 334 330 310 376 310" fill="none" stroke="#2563eb" stroke-width="4" marker-end="url(#arrow)"/>
<path d="M592 240 C642 220 650 210 690 210" fill="none" stroke="#12b76a" stroke-width="4" marker-end="url(#arrow-green)"/> <path d="M592 240 C642 220 650 210 690 210" fill="none" stroke="#12b76a" stroke-width="4" marker-end="url(#arrow-green)"/>
<path d="M592 302 C642 324 650 346 690 346" fill="none" stroke="#12b76a" stroke-width="4" marker-end="url(#arrow-green)"/> <path d="M592 302 C642 324 650 346 690 346" fill="none" stroke="#12b76a" stroke-width="4" marker-end="url(#arrow-green)"/>
<text x="306" y="178" fill="#344054" font-size="14" font-weight="700">send / receive frames</text> <text x="316" y="178" fill="#344054" font-size="13" font-weight="700">send / receive</text>
<text x="636" y="142" fill="#344054" font-size="14" font-weight="700">ConnectionManager</text> <text x="668" y="142" fill="#344054" font-size="13" font-weight="700">Room manager</text>
</g> </g>
<defs> <defs>
<marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"> <marker id="arrow" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.1 KiB

After

Width:  |  Height:  |  Size: 3.1 KiB

4
docs/images/websocket-handshake.svg
View File

@@ -3,7 +3,7 @@
<desc id="desc">A browser and server upgrade an HTTP connection to WebSocket and then exchange frames.</desc> <desc id="desc">A browser and server upgrade an HTTP connection to WebSocket and then exchange frames.</desc>
<rect width="960" height="540" fill="#f7f9fc"/> <rect width="960" height="540" fill="#f7f9fc"/>
<text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">HTTP Upgrade to WebSocket</text> <text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">HTTP Upgrade to WebSocket</text>
<text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="17">The connection starts as HTTP, then switches protocols after the handshake.</text> <text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="16">The connection starts as HTTP, then switches protocols after the handshake.</text>
<g font-family="Inter, Arial, sans-serif"> <g font-family="Inter, Arial, sans-serif">
<rect x="86" y="202" width="210" height="126" rx="18" fill="#ffffff" stroke="#d0d5dd"/> <rect x="86" y="202" width="210" height="126" rx="18" fill="#ffffff" stroke="#d0d5dd"/>
<text x="139" y="260" fill="#101828" font-size="22" font-weight="700">Browser</text> <text x="139" y="260" fill="#101828" font-size="22" font-weight="700">Browser</text>
@@ -17,7 +17,7 @@
<text x="376" y="250" fill="#344054" font-size="15" font-weight="700">2. 101 Switching Protocols</text> <text x="376" y="250" fill="#344054" font-size="15" font-weight="700">2. 101 Switching Protocols</text>
<line x1="310" y1="326" x2="650" y2="326" stroke="#7a5af8" stroke-width="4" stroke-dasharray="10 9" marker-end="url(#arrow-purple)"/> <line x1="310" y1="326" x2="650" y2="326" stroke="#7a5af8" stroke-width="4" stroke-dasharray="10 9" marker-end="url(#arrow-purple)"/>
<line x1="650" y1="362" x2="310" y2="362" stroke="#7a5af8" stroke-width="4" stroke-dasharray="10 9" marker-end="url(#arrow-purple)"/> <line x1="650" y1="362" x2="310" y2="362" stroke="#7a5af8" stroke-width="4" stroke-dasharray="10 9" marker-end="url(#arrow-purple)"/>
<text x="376" y="410" fill="#344054" font-size="15" font-weight="700">3. Full-duplex WebSocket frames over the same TCP connection</text> <text x="342" y="410" fill="#344054" font-size="15" font-weight="700">3. Full-duplex frames over the same TCP connection</text>
</g> </g>
<defs> <defs>
<marker id="arrow-blue" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto"> <marker id="arrow-blue" markerWidth="12" markerHeight="12" refX="10" refY="6" orient="auto">
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.6 KiB

After

Width:  |  Height:  |  Size: 2.6 KiB

7
docs/images/websocket-history.svg
View File

@@ -3,7 +3,7 @@
<desc id="desc">A minimal timeline showing the evolution from AJAX polling to the WebSocket RFC.</desc> <desc id="desc">A minimal timeline showing the evolution from AJAX polling to the WebSocket RFC.</desc>
<rect width="960" height="540" fill="#f7f9fc"/> <rect width="960" height="540" fill="#f7f9fc"/>
<text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">WebSocket History</text> <text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">WebSocket History</text>
<text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="17">From repeated HTTP requests to one persistent full-duplex connection</text> <text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="16">From repeated HTTP requests to one persistent full-duplex connection</text>
<line x1="110" y1="278" x2="850" y2="278" stroke="#c7d7fe" stroke-width="8" stroke-linecap="round"/> <line x1="110" y1="278" x2="850" y2="278" stroke="#c7d7fe" stroke-width="8" stroke-linecap="round"/>
<g font-family="Inter, Arial, sans-serif"> <g font-family="Inter, Arial, sans-serif">
<circle cx="150" cy="278" r="22" fill="#2563eb"/> <circle cx="150" cy="278" r="22" fill="#2563eb"/>
@@ -27,6 +27,7 @@
<text x="752" y="366" fill="#475467" font-size="15">Chat, games,</text> <text x="752" y="366" fill="#475467" font-size="15">Chat, games,</text>
<text x="740" y="388" fill="#475467" font-size="15">dashboards, IoT</text> <text x="740" y="388" fill="#475467" font-size="15">dashboards, IoT</text>
</g> </g>
<rect x="72" y="150" width="816" height="74" rx="14" fill="#ffffff" stroke="#d0d5dd"/> <rect x="72" y="150" width="816" height="86" rx="14" fill="#ffffff" stroke="#d0d5dd"/>
<text x="106" y="194" fill="#344054" font-family="Inter, Arial, sans-serif" font-size="18">Problem: browsers needed fast server-to-client updates without repeatedly opening new HTTP requests.</text> <text x="106" y="186" fill="#344054" font-family="Inter, Arial, sans-serif" font-size="16" font-weight="700">Problem</text>
<text x="106" y="212" fill="#344054" font-family="Inter, Arial, sans-serif" font-size="15">Browsers needed fast server-to-client updates without repeatedly opening new HTTP requests.</text>
</svg> </svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.5 KiB

After

Width:  |  Height:  |  Size: 2.6 KiB

6
docs/images/websocket-osi.svg
View File

@@ -3,11 +3,11 @@
<desc id="desc">A simplified OSI layer diagram showing WebSocket as an application-layer protocol over TCP and IP.</desc> <desc id="desc">A simplified OSI layer diagram showing WebSocket as an application-layer protocol over TCP and IP.</desc>
<rect width="960" height="540" fill="#f7f9fc"/> <rect width="960" height="540" fill="#f7f9fc"/>
<text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">WebSocket in the OSI Model</text> <text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">WebSocket in the OSI Model</text>
<text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="17">WebSocket is used by applications, while TCP/IP carries the bytes through the network.</text> <text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="16">WebSocket is used by applications, while TCP/IP carries bytes through the network.</text>
<g font-family="Inter, Arial, sans-serif" font-size="18"> <g font-family="Inter, Arial, sans-serif" font-size="16">
<rect x="116" y="145" width="728" height="56" rx="12" fill="#2563eb"/> <rect x="116" y="145" width="728" height="56" rx="12" fill="#2563eb"/>
<text x="148" y="181" fill="#ffffff" font-weight="700">Layer 7 - Application</text> <text x="148" y="181" fill="#ffffff" font-weight="700">Layer 7 - Application</text>
<text x="492" y="181" fill="#ffffff">HTTP handshake, then WebSocket frames</text> <text x="492" y="181" fill="#ffffff">HTTP upgrade, then WebSocket frames</text>
<rect x="116" y="211" width="728" height="48" rx="12" fill="#ffffff" stroke="#d0d5dd"/> <rect x="116" y="211" width="728" height="48" rx="12" fill="#ffffff" stroke="#d0d5dd"/>
<text x="148" y="242" fill="#344054" font-weight="700">Layer 6 - Presentation</text> <text x="148" y="242" fill="#344054" font-weight="700">Layer 6 - Presentation</text>
<text x="492" y="242" fill="#667085">Text, JSON, UTF-8</text> <text x="492" y="242" fill="#667085">Text, JSON, UTF-8</text>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.2 KiB

After

Width:  |  Height:  |  Size: 2.2 KiB

10
docs/images/websocket-pros-cons.svg
View File

@@ -3,18 +3,18 @@
<desc id="desc">A two-column diagram listing strengths and tradeoffs of WebSocket.</desc> <desc id="desc">A two-column diagram listing strengths and tradeoffs of WebSocket.</desc>
<rect width="960" height="540" fill="#f7f9fc"/> <rect width="960" height="540" fill="#f7f9fc"/>
<text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">Pros and Cons</text> <text x="72" y="74" fill="#101828" font-family="Inter, Arial, sans-serif" font-size="34" font-weight="700">Pros and Cons</text>
<text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="17">WebSocket is powerful for real-time systems, but it changes server and network responsibilities.</text> <text x="72" y="108" fill="#667085" font-family="Inter, Arial, sans-serif" font-size="16">WebSocket is powerful for real-time systems, with some server and network tradeoffs.</text>
<g font-family="Inter, Arial, sans-serif"> <g font-family="Inter, Arial, sans-serif">
<rect x="92" y="152" width="350" height="298" rx="20" fill="#ecfdf3" stroke="#abefc6"/> <rect x="92" y="152" width="350" height="298" rx="20" fill="#ecfdf3" stroke="#abefc6"/>
<text x="130" y="202" fill="#067647" font-size="24" font-weight="700">Pros</text> <text x="130" y="202" fill="#067647" font-size="24" font-weight="700">Pros</text>
<circle cx="136" cy="250" r="7" fill="#12b76a"/><text x="158" y="256" fill="#344054" font-size="17">Low latency updates</text> <circle cx="136" cy="250" r="7" fill="#12b76a"/><text x="158" y="256" fill="#344054" font-size="17">Low latency updates</text>
<circle cx="136" cy="296" r="7" fill="#12b76a"/><text x="158" y="302" fill="#344054" font-size="17">Full-duplex communication</text> <circle cx="136" cy="296" r="7" fill="#12b76a"/><text x="158" y="302" fill="#344054" font-size="17">Full-duplex communication</text>
<circle cx="136" cy="342" r="7" fill="#12b76a"/><text x="158" y="348" fill="#344054" font-size="17">Less HTTP overhead after setup</text> <circle cx="136" cy="342" r="7" fill="#12b76a"/><text x="158" y="348" fill="#344054" font-size="16">Less HTTP overhead</text>
<circle cx="136" cy="388" r="7" fill="#12b76a"/><text x="158" y="394" fill="#344054" font-size="17">Great for chat and live dashboards</text> <circle cx="136" cy="388" r="7" fill="#12b76a"/><text x="158" y="394" fill="#344054" font-size="16">Great for chat and dashboards</text>
<rect x="518" y="152" width="350" height="298" rx="20" fill="#fff1f3" stroke="#fecdd3"/> <rect x="518" y="152" width="350" height="298" rx="20" fill="#fff1f3" stroke="#fecdd3"/>
<text x="556" y="202" fill="#b42318" font-size="24" font-weight="700">Cons</text> <text x="556" y="202" fill="#b42318" font-size="24" font-weight="700">Cons</text>
<circle cx="562" cy="250" r="7" fill="#f04438"/><text x="584" y="256" fill="#344054" font-size="17">Long-lived connections use memory</text> <circle cx="562" cy="250" r="7" fill="#f04438"/><text x="584" y="256" fill="#344054" font-size="16">Long-lived connections use memory</text>
<circle cx="562" cy="296" r="7" fill="#f04438"/><text x="584" y="302" fill="#344054" font-size="17">Scaling needs shared state or brokers</text> <circle cx="562" cy="296" r="7" fill="#f04438"/><text x="584" y="302" fill="#344054" font-size="16">Scaling needs shared state</text>
<circle cx="562" cy="342" r="7" fill="#f04438"/><text x="584" y="348" fill="#344054" font-size="17">More connection failure cases</text> <circle cx="562" cy="342" r="7" fill="#f04438"/><text x="584" y="348" fill="#344054" font-size="17">More connection failure cases</text>
<circle cx="562" cy="388" r="7" fill="#f04438"/><text x="584" y="394" fill="#344054" font-size="17">Not ideal for simple CRUD pages</text> <circle cx="562" cy="388" r="7" fill="#f04438"/><text x="584" y="394" fill="#344054" font-size="17">Not ideal for simple CRUD pages</text>
</g> </g>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.1 KiB

After

Width:  |  Height:  |  Size: 2.1 KiB

196
presentation.md
View File

@@ -1,36 +1,36 @@
# Presentation: Simple WebSocket Chatroom # ارائه: چت‌روم ساده با WebSocket
## Slide 1 - Project Title ## اسلاید ۱ - عنوان پروژه
**Simple WebSocket Chatroom** **چت‌روم ساده با WebSocket**
A university Internet Engineering project that demonstrates real-time communication with FastAPI, WebSocket, and a Persian browser UI. این پروژه برای درس مهندسی اینترنت آماده شده است و هدف آن نمایش ارتباط بلادرنگ بین مرورگر و سرور با استفاده از FastAPI و WebSocket است.
![Chatroom architecture](docs/images/chatroom-architecture.svg) ![معماری چت‌روم](docs/images/chatroom-architecture.svg)
## Slide 2 - Why WebSocket Exists ## اسلاید ۲ - چرا WebSocket به وجود آمد؟
Early web pages mostly used the HTTP request/response model. The browser asked for a document, the server returned it, and the connection finished. وب در ابتدا بیشتر بر پایه مدل درخواست و پاسخ HTTP کار می‌کرد. مرورگر یک درخواست می‌فرستاد، سرور پاسخ می‌داد و ارتباط همان‌جا تمام می‌شد.
When web applications started needing live updates, developers used techniques such as polling and long polling. These methods worked, but they repeated HTTP requests many times and created unnecessary overhead. با پیچیده‌تر شدن برنامه‌های وب، نیاز به دریافت سریع اطلاعات جدید از سمت سرور بیشتر شد؛ مثلا پیام جدید در چت، اعلان‌ها یا وضعیت زنده یک سیستم.
WebSocket was introduced to give web applications one persistent connection that can carry messages in both directions. قبل از WebSocket معمولا از روش‌هایی مثل polling و long polling استفاده می‌شد. این روش‌ها قابل استفاده بودند، اما باعث تکرار زیاد درخواست‌های HTTP و مصرف منابع بیشتر می‌شدند.
![WebSocket history timeline](docs/images/websocket-history.svg) ![تاریخچه WebSocket](docs/images/websocket-history.svg)
## Slide 3 - Short History ## اسلاید ۳ - تاریخچه کوتاه
- **Classic HTTP:** good for documents and forms, but not designed for instant server push. - **HTTP کلاسیک:** برای دریافت صفحه و ارسال فرم مناسب بود، اما برای ارسال لحظه‌ای داده از سرور به مرورگر طراحی نشده بود.
- **AJAX and polling:** allowed background requests, but the browser still had to keep asking the server for updates. - **AJAX و polling:** امکان درخواست‌های پس‌زمینه را فراهم کرد، ولی مرورگر همچنان باید مرتب از سرور سوال می‌پرسید.
- **Long polling:** reduced useless requests, but each update still involved HTTP request handling. - **Long polling:** تعداد درخواست‌های بی‌فایده را کمتر کرد، اما همچنان هر پیام جدید درگیر چرخه HTTP بود.
- **WebSocket standardization:** RFC 6455 defined WebSocket as a standard protocol for full-duplex browser/server communication. - **استاندارد WebSocket:** در RFC 6455 به عنوان یک پروتکل استاندارد برای ارتباط دوطرفه و پایدار معرفی شد.
- **Modern usage:** chat apps, games, live dashboards, collaborative editors, notifications, and IoT control panels. - **کاربردهای امروز:** چت، بازی آنلاین، داشبورد زنده، ویرایش هم‌زمان، اعلان‌ها و کنترل تجهیزات IoT.
## Slide 4 - How WebSocket Starts on HTTP ## اسلاید ۴ - WebSocket چگونه از HTTP شروع می‌شود؟
WebSocket does not begin as a completely separate browser mechanism. It starts with an HTTP request that asks the server to upgrade the connection. WebSocket از ابتدا یک ارتباط جدا از HTTP نیست. ارتباط با یک درخواست HTTP معمولی شروع می‌شود که از سرور می‌خواهد پروتکل را تغییر دهد.
The browser sends an HTTP `GET` request with headers such as: مرورگر یک درخواست `GET` با سرآیندهایی شبیه این می‌فرستد:
```text ```text
Connection: Upgrade Connection: Upgrade
@@ -38,127 +38,127 @@ Upgrade: websocket
Sec-WebSocket-Key: ... Sec-WebSocket-Key: ...
``` ```
If the server accepts the upgrade, it responds with: اگر سرور درخواست را قبول کند، پاسخ زیر را برمی‌گرداند:
```text ```text
101 Switching Protocols 101 Switching Protocols
``` ```
After that response, the same TCP connection is no longer used as normal HTTP. It carries WebSocket frames. بعد از این پاسخ، همان اتصال TCP دیگر مثل HTTP عادی استفاده نمی‌شود و داده‌ها در قالب فریم‌های WebSocket جابه‌جا می‌شوند.
![HTTP upgrade handshake](docs/images/websocket-handshake.svg) ![فرایند ارتقای HTTP](docs/images/websocket-handshake.svg)
## Slide 5 - After the Upgrade ## اسلاید ۵ - بعد از ارتقا چه اتفاقی می‌افتد؟
Once the connection is upgraded: بعد از تبدیل ارتباط:
- The browser can send messages to the server at any time. - مرورگر هر زمان بخواهد می‌تواند برای سرور پیام بفرستد.
- The server can send messages to the browser at any time. - سرور هم هر زمان بخواهد می‌تواند برای مرورگر پیام بفرستد.
- Both sides keep the same connection open. - ارتباط باز می‌ماند و برای هر پیام، درخواست HTTP جدید ساخته نمی‌شود.
- Data is sent as WebSocket frames instead of repeated HTTP requests. - داده‌ها به صورت فریم WebSocket ارسال می‌شوند.
This is why WebSocket is called **full-duplex** communication. به همین دلیل به WebSocket ارتباط **دوطرفه کامل** گفته می‌شود.
## Slide 6 - WebSocket in the OSI Model ## اسلاید ۶ - جایگاه WebSocket در مدل OSI
WebSocket is usually discussed at the **application layer** because application code decides what messages mean. WebSocket معمولا در لایه کاربرد بررسی می‌شود، چون برنامه تصمیم می‌گیرد پیام‌ها چه معنایی دارند.
In a typical browser/server setup: در یک ارتباط معمول بین مرورگر و سرور:
- WebSocket is used by the application. - برنامه از WebSocket برای ارسال و دریافت پیام استفاده می‌کند.
- The opening handshake uses HTTP semantics. - شروع ارتباط با مفاهیم HTTP انجام می‌شود.
- The reliable transport is TCP. - انتقال قابل اعتماد داده‌ها بر عهده TCP است.
- IP routes packets between machines. - IP بسته‌ها را بین میزبان‌ها مسیریابی می‌کند.
- Ethernet or Wi-Fi carries the actual signals. - Ethernet یا Wi-Fi داده را روی شبکه واقعی حمل می‌کند.
![WebSocket in OSI model](docs/images/websocket-osi.svg) ![جایگاه WebSocket در مدل OSI](docs/images/websocket-osi.svg)
## Slide 7 - Network View ## اسلاید ۷ - نگاه شبکه‌ای ساده
The stack can be simplified like this: مسیر داده در این پروژه را می‌توان این‌طور ساده کرد:
```text ```text
Chat message JSON پیام چت در قالب JSON
WebSocket frame فریم WebSocket
TCP segment قطعه TCP
IP packet بسته IP
Network frame فریم شبکه
Physical signal سیگنال فیزیکی
``` ```
The chatroom code mostly works at the top of this stack. It creates JSON messages, sends them through a WebSocket, and lets the operating system and network layers handle delivery. کد پروژه بیشتر در بالاترین بخش این زنجیره کار می‌کند. پیام JSON ساخته می‌شود، از طریق WebSocket فرستاده می‌شود و جزئیات انتقال در لایه‌های پایین‌تر توسط سیستم‌عامل و شبکه انجام می‌شود.
## Slide 8 - Project Architecture ## اسلاید ۸ - معماری پروژه
This project has three main parts: این پروژه سه بخش اصلی دارد:
- **Browser UI:** HTML, CSS, and JavaScript. - **رابط مرورگر:** فایل‌های HTML، CSS و JavaScript.
- **WebSocket endpoint:** FastAPI route at `/ws/{room_id}/{client_id}`. - **مسیر WebSocket:** مسیر FastAPI با الگوی `/ws/{room_id}/{client_id}`.
- **Connection manager:** stores active sockets grouped by room. - **مدیر اتصال‌ها:** نگهداری socketهای فعال به تفکیک اتاق.
When a user sends a message, the server receives it from one socket and broadcasts it to all sockets in the same room. وقتی یک کاربر پیام می‌فرستد، سرور پیام را از socket همان کاربر می‌گیرد و آن را برای همه socketهای همان اتاق پخش می‌کند.
![Project architecture](docs/images/chatroom-architecture.svg) ![معماری پروژه](docs/images/chatroom-architecture.svg)
## Slide 9 - Message Flow in This Project ## اسلاید ۹ - جریان پیام در پروژه
1. User enters a name and room. 1. کاربر نام و اتاق را وارد می‌کند.
2. JavaScript creates a `WebSocket` object. 2. JavaScript یک شیء `WebSocket` می‌سازد.
3. Browser sends the HTTP upgrade request. 3. مرورگر درخواست HTTP Upgrade را ارسال می‌کند.
4. FastAPI accepts the WebSocket connection. 4. FastAPI اتصال WebSocket را قبول می‌کند.
5. The connection manager stores the user in the selected room. 5. مدیر اتصال، کاربر را در لیست اتاق ذخیره می‌کند.
6. A message is sent as JSON from browser to server. 6. پیام به صورت JSON از مرورگر به سرور فرستاده می‌شود.
7. The server broadcasts the message to everyone in that room. 7. سرور پیام را برای کاربران همان اتاق پخش می‌کند.
8. Browsers render the received message without page refresh. 8. مرورگرها پیام جدید را بدون تازه‌سازی صفحه نمایش می‌دهند.
## Slide 10 - Pros and Cons ## اسلاید ۱۰ - مزایا و معایب
WebSocket is useful, but it is not the correct choice for every web page. WebSocket برای سیستم‌های بلادرنگ بسیار کاربردی است، اما برای همه صفحه‌های وب انتخاب لازم یا مناسب نیست.
![WebSocket pros and cons](docs/images/websocket-pros-cons.svg) ![مزایا و معایب WebSocket](docs/images/websocket-pros-cons.svg)
## Slide 11 - Advantages ## اسلاید ۱۱ - مزایا
- Low latency because the connection stays open. - تاخیر کم، چون ارتباط باز می‌ماند.
- Server can push data immediately. - امکان ارسال فوری داده از سمت سرور به مرورگر.
- Good fit for chat, notifications, collaborative tools, games, and live dashboards. - مناسب برای چت، اعلان، ابزارهای همکاری، بازی و داشبورد زنده.
- Less repeated HTTP header overhead after the initial upgrade. - کاهش سربار سرآیندهای تکراری HTTP بعد از دست‌دهی اولیه.
- Simple programming model for continuous two-way messaging. - مدل برنامه‌نویسی ساده برای ارتباط پیوسته و دوطرفه.
## Slide 12 - Disadvantages ## اسلاید ۱۲ - معایب
- Long-lived connections consume server resources. - اتصال‌های طولانی‌مدت از منابع سرور استفاده می‌کنند.
- Scaling across multiple servers needs extra design, such as Redis Pub/Sub or a message broker. - مقیاس‌پذیری روی چند سرور به طراحی بیشتر نیاز دارد.
- Disconnections, reconnects, and network failures must be handled carefully. - قطع اتصال، اتصال دوباره و خطاهای شبکه باید مدیریت شوند.
- Some proxies and firewalls may need correct WebSocket support. - بعضی پراکسی‌ها یا دیواره‌های آتش ممکن است تنظیم درست برای WebSocket بخواهند.
- It is unnecessary for simple pages that only need normal request/response behavior. - برای صفحه‌های ساده CRUD معمولا لازم نیست.
## Slide 13 - Why This Project Is Kept Simple ## اسلاید ۱۳ - چرا پروژه ساده نگه داشته شده است؟
This project intentionally avoids accounts, databases, authentication, message history, and deployment complexity. در این پروژه عمدا ثبت‌نام، پایگاه داده، احراز هویت، تاریخچه پیام‌ها و پیچیدگی‌های استقرار اضافه نشده‌اند.
The goal is to make the WebSocket behavior easy to see: هدف این است که رفتار اصلی WebSocket واضح دیده شود:
- open connection - باز شدن اتصال
- join room - ورود به اتاق
- send message - ارسال پیام
- broadcast message - پخش پیام برای کاربران اتاق
- close connection - بسته شدن اتصال
That makes it suitable for a classroom demonstration. این سادگی پروژه را برای ارائه کلاسی مناسب‌تر می‌کند.
## Slide 14 - Demo Plan ## اسلاید ۱۴ - برنامه اجرای دمو
1. Run the server with `uvicorn app.main:app --reload`. 1. سرور را با دستور `uvicorn app.main:app --reload` اجرا کنید.
2. Open the app in two browser tabs. 2. برنامه را در دو تب مرورگر باز کنید.
3. Enter two different names. 3. در هر تب یک نام متفاوت وارد کنید.
4. Join the same room. 4. هر دو کاربر وارد یک اتاق شوند.
5. Send a message from one tab. 5. از یک تب پیام ارسال کنید.
6. Show that the second tab receives it instantly. 6. دریافت فوری پیام در تب دوم را نشان دهید.
7. Disconnect one user and show the online users list updating. 7. یکی از کاربران را قطع کنید و تغییر فهرست کاربران آنلاین را نمایش دهید.
## Slide 15 - Conclusion ## اسلاید ۱۵ - جمع‌بندی
WebSocket solves the real-time web communication problem by upgrading an HTTP connection into a persistent, full-duplex channel. WebSocket مشکل ارتباط بلادرنگ در وب را با تبدیل یک اتصال HTTP به یک کانال پایدار و دوطرفه حل می‌کند.
In this chatroom project, that concept is demonstrated with a small FastAPI backend and a simple Persian browser interface. در این چت‌روم، همین مفهوم با یک بخش سرور کوچک FastAPI و یک رابط فارسی ساده نمایش داده شده است.