# ఆర్కిటెక్చర్

## సిస్టమ్ పరిచయం

```
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
- హోస్ట్ చేసిన వెబ్ యాప్ కోసం ఉమ్మడి డొమైన్ బ్రౌజర్ సెషన్ కుకీలు
- దీర్ఘకాల ApiKey ని అందించే, `auth.<domain>` పై ఏజెంట్ OTP ప్రారంభ సెటప్
- లోకల్ డెవలప్‌మెంట్ కోసం `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/te/docs/architecture/>)*

*AI ఏజెంట్లు `GET https://api.nibomo.com/v1/` తో మొదలుపెట్టి ఈ సేవలో వినియోగదారుకు ఖాతా సృష్టించగలవు. సెటప్ అయ్యాక అవి `https://mcp.nibomo.com/mcp` వద్ద MCP ద్వారా కూడా అనుసంధానం కాగలవు.*

*చిట్కా: https://nibomo.com లోని ఏ URL చివరన అయినా `.md` జోడిస్తే ఆ పేజీ యొక్క శుభ్రమైన Markdown వెర్షన్ వస్తుంది.*