نقشه دایرکتوری server/ و محتویات آن.

نقشه پروژه و درخت

دایرکتوری server/ شامل بک‌اند Go و media server LiveKit جاسازی‌شده است. دایرکتوری apps/ شامل برنامه‌های کلاینت است.

bedrud/
├── apps/                # برنامه‌های کلاینت
│   ├── web/             # فرانت‌اند React (TanStack Start)
│   ├── android/         # برنامه بومی Android
│   └── ios/             # برنامه بومی iOS
├── server/              # بک‌اند Go ("دستگاه")
│   ├── cmd/             # نقاط ورودی CLI (run, install)
│   ├── internal/        # کد برنامه خصوصی
│   │   ├── auth/        # منطق JWT، کلیدهای عبور، OAuth
│   │   ├── handlers/    # کنترلرهای HTTP
│   │   ├── models/      # طرح‌واره‌های دیتابیس
│   │   ├── repository/  # لایه دسترسی به داده GORM
│   │   └── livekit/     # مدیریت media server
│   ├── frontend/        # (تولیدشده) دارایی‌های وب کامپایل‌شده
│   ├── config.yaml      # الگوی پیکربندی
│   └── Makefile         # اتوماسیون ساخت و استقرار
└── docs/                # مستندات سیستم (MkDocs)

نقشه دایرکتوری

/cmd/bedrud

• main.go: نقطه ورودی برنامه. دستورات CLI مانند run، install و livekit را مدیریت می‌کند.

/config

• config.go: ساختار Config را تعریف می‌کند و تنظیمات را از config.yaml یا متغیرهای محیطی بارگذاری می‌کند.
• livekit.yaml: پیکربندی پیش‌فرض برای سرور LiveKit جاسازی‌شده.

/internal

• /auth: شامل منطق برای تولید JWT، ارائه‌دهندگان OAuth، و ثبت‌نام/ورود کلید عبور (WebAuthn).
• /database: اتصال به SQLite یا PostgreSQL را مدیریت می‌کند و مهاجرت‌ها را اجرا می‌کند.
• /handlers: هندلرهای HTTP Fiber. جایی که منطق هر نقطه پایانی API را پیدا می‌کنید (مثلاً auth_handler.go، room_handler.go).
• /models: مدل‌های دیتابیس GORM. این فایل‌ها جداول دیتابیس شما را تعریف می‌کنند.
• /repository: “لایه دسترسی به داده”. هندلرها به جای نوشتن پرس‌وجوهای DB مستقیم، مخازن را فراخوانی می‌کنند، که منطق هندلر را تمیز نگه می‌دارد.
• /livekit: یکپارچگی با LiveKit Go SDK. ایجاد اتاق را مدیریت می‌کند و “توکن‌های پیوستن” برای شرکت‌کنندگان تولید می‌کند.
• /middleware: middlewareهای Fiber سفارشی برای بررسی‌های احراز هویت، لاگ و CORS.
• /server: کد چسب‌اندن که همه چیز را به هم می‌آورد. دیتابیس، مخازن را مقداردهی اولیه می‌کند و سرور Fiber را شروع می‌کند.
• /install: منطق برای دستور bedrud install که systemd و TLS را در Linux خودکار می‌کند.
• /scheduler: وظایف پس‌زمینه (اگر وجود داشته باشد).
• /utils: توابع کمک‌کننده کوچک (مثلاً هش کردن رمز عبور، رشته‌های تصادفی).

/migrations

• شامل فایل‌های SQL یا Go برای به‌روزرسانی طرح‌واره دیتابیس.

/docs (درون سرور)

• شامل فایل‌های مستندات Swagger/OpenAPI (تولیدشده توسط swag).

غوطه‌وری فنی

۱. جاسازی باینری (“حقه”)

Bedrud از دستور //go:embed برای بسته‌بندی فایل‌ها در باینری کامپایل‌شده استفاده می‌کند.

• فرانت‌اند: پوشه React dist/client/ (به علاوه یک index.html از پیش رندرشده) در server/ui.go جاسازی می‌شود. فایل‌های استاتیک مستقیماً از حافظه با استفاده از middleware filesystem Fiber سرو می‌شوند.
• سرور LiveKit: فایل اجرایی livekit-server از پیش کامپایل‌شده در internal/livekit/bin/ جاسازی می‌شود. در زمان اجرا، Bedrud آن را به /tmp/bedrud-livekit-server استخراج می‌کند و به عنوان یک فرآیند پس‌زمینه راه‌اندازی می‌کند (internal/livekit/server.go).

۲. reverse proxy LiveKit

برای جلوگیری از باز کردن چندین پورت (سیگنالینگ، API و غیره)، Bedrud تمام ترافیک سیگنالینگ LiveKit را از طریق پورت اصلی HTTP(S) خود مسیریابی می‌کند.

• هر درخواستی که با /livekit شروع شود در internal/server/server.go رهگیری می‌شود.
• یک reverse proxy (با استفاده از httputil.NewSingleHostReverseProxy) این درخواست‌ها را به نمونه LiveKit داخلی (معمولاً در حال اجرا روی 127.0.0.1:7880) ارسال می‌کند.
• پروکسی پیشوند /livekit را قبل از ارسال حذف می‌کند، که به LiveKit اجازه می‌دهد گویی برنامه اصلی است عمل کند.

۳. زمینه و Locals middleware

بک‌اند از .Locals Fiber برای ارسال داده‌ها بین middleware و هندلرها استفاده می‌کند.

• middleware احراز هویت (internal/middleware/auth.go): JWT را تأیید می‌کند و شیء Claims را در c.Locals("user") ذخیره می‌کند.
• هندلرها: می‌توانند با استفاده از کد زیر به شناسه و مجوزهای کاربر فعلی دسترسی داشته باشند:

claims := c.Locals("user").(*auth.Claims)
userID := claims.UserID

۴. بازنویسی پیکربندی

در حالی که Bedrud از یک فایل config.yaml استفاده می‌کند، تقریباً هر تنظیم می‌تواند با استفاده از متغیرهای محیطی بازنویسی شود. این برای محیط‌های Docker و CI/CD ضروری است.

استانداردها و الگوهای کدنویسی

بک‌اند این الگوها را دنبال می‌کند:

۱. الگوی مخزن

هندلرها نباید مستقیماً با دیتابیس صحبت کنند. از یک مخزن استفاده کنید. این کد را آسان‌تر برای تست می‌کند و اجازه می‌دهد منطق دیتابیس بدون لمس هندلرهای API تغییر کند.

۲. مدیریت خطای استانداردشده

هندلرهای API باید پیام‌های خطای واضح برگردانند.

• از c.Status(fiber.StatusBadRequest).JSON(...) برای خطاهای اعتبارسنجی استفاده کنید.
• از c.Status(fiber.StatusUnauthorized).JSON(...) برای خطاهای احراز هویت استفاده کنید.
• از c.Status(fiber.StatusInternalServerError).JSON(...) برای خطاهای دیتابیس یا سرور استفاده کنید.

۳. لاگ ساختاریافته

بک‌اند از Zerolog برای لاگ استفاده می‌کند.

• log.Info(): برای رویدادهای مهم (مثلاً سرور شروع شد).
• log.Error(): برای شکست‌ها.
• log.Debug(): برای اطلاعات توسعه تفصیلی.

از استفاده از fmt.Println برای لاگ در منطق اصلی خودداری کنید.

۴. کنوانسیون‌های نامگذاری

• فایل‌ها: snake_case (مثلاً user_handler.go).
• ساختارها/توابع: PascalCase (مثلاً GetUserByEmail).
• متغیرها: camelCase (مثلاً hashedPassword).