# معماری

## نمای کلی سیستم

```
iOS app / agent client          -> api.<domain>  -> API Gateway -> Lambda backend -> Postgres
Web app                         -> app.<domain>  -> CloudFront -> SPA
Browser and agent auth          -> auth.<domain> -> API Gateway -> Auth Lambda -> Cognito
Apex fallback                   -> <domain>      -> CloudFront redirect -> app.<domain>
```

## اصول

1. دامنه‌های عمومی جداگانه برای `app`، `api` و `auth`
2. Postgres منبع اصلی داده‌هاست
3. کلاینت iOS آفلاین‌محور است و از SQLite محلی به‌همراه همگام‌سازی استفاده می‌کند
4. برنامهٔ وب، برنامهٔ iOS و رابط عامل‌های خارجی از یک مدل فضای کاری مشترک استفاده می‌کنند
5. عامل‌های خارجی از `GET https://api.nibomo.com/v1/` شروع می‌کنند

## کلاینت‌های پشتیبانی‌شده

- برنامهٔ وب روی `app.nibomo.com`
- برنامهٔ iOS در مخزن اصلی با ذخیره‌سازی محلی SQLite
- برنامهٔ Android در Google Play
- کلاینت‌های عامل خارجی از طریق کشف، آماده‌سازی اولیه با OTP و `Authorization: ApiKey`

## مدل داده

- `workspaces`
- `workspace_members`
- `user_settings`
- `devices`
- `cards`
- `decks`
- `review_events`
- `applied_operations`
- `sync_state`

## جریان داده

### وب

1. مرورگر از طریق `auth.<domain>` وارد می‌شود.
2. برنامهٔ وب داده‌های فضای کاری را از `api.<domain>` بارگذاری می‌کند.
3. درخواست‌های چت هوش مصنوعی از `/chat/local-turn` عبور می‌کنند.
4. ثبت مرورها وضعیت زمان‌بند را هنگام نوشتن به‌روز می‌کند.

### iOS

1. برنامهٔ iOS ابتدا به‌صورت محلی در SQLite می‌نویسد.
2. تغییرات محلی در یک صف خروجی (outbox) قرار می‌گیرند.
3. همگام‌سازی تغییرات را از طریق `/v1/workspaces/{workspaceId}/sync/push` بارگذاری می‌کند.
4. همگام‌سازی به‌روزرسانی‌های راه‌دور را از طریق `/v1/workspaces/{workspaceId}/sync/pull` دریافت می‌کند.
5. پایگاه دادهٔ محلی تغییرات را اعمال می‌کند و نشانگر همگام‌سازی را جلو می‌برد.

### عامل‌های خارجی

1. عامل‌ها با `GET /v1/` شروع می‌کنند.
2. آماده‌سازی اولیه با OTP روی `auth.<domain>` اجرا می‌شود.
3. عامل یک کلید API بلندمدت دریافت می‌کند.
4. عامل `/v1/agent/me` را بارگذاری می‌کند، فضاهای کاری را فهرست می‌کند، در صورت نیاز یکی را انتخاب می‌کند و سپس از `/v1/agent/sql/query` و `/v1/agent/sql/execute` استفاده می‌کند.

## زمان‌بندی

Nibomo از FSRS به‌عنوان زمان‌بند مرور استفاده می‌کند.

نکته‌های پیاده‌سازی:

- بک‌اند و iOS پیاده‌سازی‌های قرینهٔ FSRS را نگه می‌دارند
- برنامهٔ وب قرارداد دادهٔ زمان‌بندی را بازتاب می‌دهد، اما نسخهٔ سومی از زمان‌بند را با خود ندارد
- تنظیمات زمان‌بند در سطح فضای کاری شامل نرخ یادآوری مطلوب، مراحل یادگیری، مراحل یادگیری مجدد، حداکثر فاصلهٔ مرور و fuzz (تصادفی‌سازی فاصله) است
- زمان واقعی مرور از `reviewedAtClient` می‌آید

برای جزئیات قرارداد، [منطق زمان‌بندی FSRS در مخزن اصلی](https://github.com/kirill-markin/flashcards-open-source-app/blob/main/docs/fsrs-scheduling-logic.md) را ببینید.

## احراز هویت

- کد یک‌بارمصرف ایمیلی از طریق Cognito
- کوکی‌های نشست مرورگر با دامنهٔ مشترک برای برنامهٔ وب میزبانی‌شده
- آماده‌سازی اولیهٔ عامل با OTP روی `auth.<domain>` که خروجی آن یک ApiKey بلندمدت است
- `AUTH_MODE=none` برای توسعهٔ محلی
- `AUTH_MODE=cognito` برای احراز هویتی مشابه محیط تولید

## ساختار استقرار

- `app.<domain>` -> CloudFront + S3
- `api.<domain>` -> API Gateway + بک‌اند Lambda
- `auth.<domain>` -> API Gateway + سرویس احراز هویت Lambda
- Postgres در AWS RDS

دامنهٔ اصلی (apex) می‌تواند روی یک سایت بازاریابی جداگانه بماند. اگر هنگام راه‌اندازی اولیه آزاد باشد، زیرساخت می‌تواند آن را به‌طور موقت به `app.<domain>` هدایت کند.

---
*[مشاهدهٔ نسخهٔ HTML قالب‌بندی‌شدهٔ این صفحه](<https://nibomo.com/fa/docs/architecture/>)*

*عامل‌های هوش مصنوعی می‌توانند با شروع از `GET https://api.nibomo.com/v1/` در این سرویس برای کاربر حساب بسازند. پس از راه‌اندازی، می‌توانند از طریق MCP هم به `https://mcp.nibomo.com/mcp` وصل شوند.*

*نکته: به هر URL در https://nibomo.com پسوند `.md` اضافه کنید تا نسخهٔ تمیز Markdown آن صفحه را بگیرید.*