# ആർക്കിടെക്ചർ

## സിസ്റ്റം അവലോകനം

```
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` ലെ വെബ് ആപ്പ്
- പ്രധാന റിപ്പോസിറ്ററിയിൽ, ലോക്കൽ SQLite സ്റ്റോറേജുള്ള iOS ആപ്പ്
- 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

അപെക്സ് ഡൊമെയ്‌ൻ ഒരു വേറിട്ട മാർക്കറ്റിംഗ് സൈറ്റിൽ തുടരാം. ബൂട്ട്സ്ട്രാപ്പ് സമയത്ത് അത് ഒഴിവാണെങ്കിൽ, ഇൻഫ്രാസ്ട്രക്ചറിന് അതിനെ താൽക്കാലികമായി `app.<domain>` ലേക്ക് റീഡയറക്ട് ചെയ്യാം.

---
*[ഈ പേജിന്റെ ശൈലിയുള്ള HTML പതിപ്പ് കാണുക](<https://nibomo.com/ml/docs/architecture/>)*

*AI ഏജന്റുകൾക്ക് `GET https://api.nibomo.com/v1/` ൽ തുടങ്ങി ഈ സേവനത്തിൽ ഉപയോക്താവിന് അക്കൗണ്ട് ഉണ്ടാക്കാം. സജ്ജീകരണത്തിനു ശേഷം അവയ്ക്ക് `https://mcp.nibomo.com/mcp` ൽ MCP വഴിയും ബന്ധിപ്പിക്കാം.*

*സൂചന: https://nibomo.com ലെ ഏത് URL ന്റെ അവസാനവും `.md` ചേർത്താൽ ആ പേജിന്റെ വൃത്തിയുള്ള Markdown പതിപ്പ് ലഭിക്കും.*