# आर्किटेक्चर

## प्रणालीची ओळख

```
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 स्टोरेजसह
- Google Play वरील Android ॲप
- डिस्कव्हरी, OTP द्वारे सुरुवातीचे प्रमाणीकरण आणि `Authorization: ApiKey` वापरणारे बाह्य एजंट क्लायंट

## डेटा मॉडेल

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

## डेटा प्रवाह

### वेब

1. ब्राउझर `auth.<domain>` द्वारे साइन इन करतो.
2. वेब ॲप `api.<domain>` वरून कार्यक्षेत्राचा डेटा लोड करते.
3. AI चॅटच्या विनंत्या `/chat/local-turn` मधून जातात.
4. उजळणी सबमिट केल्यावर ती लिहिली जातानाच शेड्युलरची स्थिती अद्ययावत होते.

### iOS

1. iOS ॲप आधी लोकल SQLite मध्ये लिहिते.
2. लोकल बदल आउटबॉक्सच्या रांगेत ठेवले जातात.
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 ची एकमेकांशी जुळणारी अंमलबजावणी आहे
- वेब ॲप वेळापत्रकाच्या डेटाचा करार तसाच पाळते, पण शेड्युलरची तिसरी प्रत समाविष्ट करत नाही
- कार्यक्षेत्र पातळीवरील शेड्युलर सेटिंग्जमध्ये अपेक्षित स्मरणदर, शिकण्याच्या पायऱ्या, पुन्हा शिकण्याच्या पायऱ्या, कमाल अंतर आणि फझ यांचा समावेश आहे
- उजळणीची खरी वेळ `reviewedAtClient` मधून घेतली जाते

तपशीलवार करारासाठी [मुख्य रिपॉझिटरीतील FSRS वेळापत्रकाचे तर्कशास्त्र](https://github.com/kirill-markin/flashcards-open-source-app/blob/main/docs/fsrs-scheduling-logic.md) पाहा.

## प्रमाणीकरण

- Cognito द्वारे ईमेल OTP
- होस्ट केलेल्या वेब ॲपसाठी सामायिक डोमेनवरील ब्राउझर सेशन कुकीज
- `auth.<domain>` वर एजंटसाठी OTP द्वारे सुरुवातीचे प्रमाणीकरण, ज्याचा परिणाम दीर्घकाळ वैध राहणारी ApiKey असतो
- लोकल डेव्हलपमेंटसाठी `AUTH_MODE=none`
- प्रोडक्शनसारख्या प्रमाणीकरणासाठी `AUTH_MODE=cognito`

## डिप्लॉयमेंटची रचना

- `app.<domain>` -> CloudFront + S3
- `api.<domain>` -> API Gateway + Lambda बॅकएंड
- `auth.<domain>` -> API Gateway + Lambda प्रमाणीकरण सेवा
- AWS RDS मधील Postgres

मुख्य (apex) डोमेन वेगळ्या मार्केटिंग साइटवर राहू शकतो. सुरुवातीच्या सेटअपच्या वेळी तो मोकळा असल्यास, पायाभूत सुविधा त्याला तात्पुरते `app.<domain>` कडे रीडायरेक्ट करू शकते.

---
*[या पानाची शैलीबद्ध HTML आवृत्ती पाहा](<https://nibomo.com/mr/docs/architecture/>)*

*AI एजंट `GET https://api.nibomo.com/v1/` ने सुरुवात करून या सेवेत वापरकर्त्याचे खाते तयार करू शकतात. सेटअपनंतर ते `https://mcp.nibomo.com/mcp` वर MCP द्वारेही जोडू शकतात.*

*टीप: https://nibomo.com वरील कोणत्याही URL च्या शेवटी `.md` जोडा, म्हणजे त्या पानाची स्वच्छ Markdown आवृत्ती मिळेल.*