# Αρχιτεκτονική

## Επισκόπηση του συστήματος

```
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. Τα αιτήματα της συνομιλίας 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 για τον προγραμματισμό των επαναλήψεων.

Σημειώσεις υλοποίησης:

- το backend και το iOS διατηρούν πανομοιότυπες υλοποιήσεις του FSRS
- η εφαρμογή ιστού ακολουθεί το ίδιο συμβόλαιο δεδομένων προγραμματισμού, αλλά δεν περιέχει τρίτο αντίγραφο του χρονοπρογραμματιστή
- οι ρυθμίσεις του χρονοπρογραμματιστή σε επίπεδο χώρου εργασίας περιλαμβάνουν την επιθυμητή διατήρηση, τα βήματα εκμάθησης, τα βήματα επανεκμάθησης, το μέγιστο διάστημα και το fuzz
- η πραγματική χρονοσήμανση της επανάληψης προέρχεται από το `reviewedAtClient`

Για το αναλυτικό συμβόλαιο, δείτε τη [λογική προγραμματισμού FSRS στο κύριο αποθετήριο](https://github.com/kirill-markin/flashcards-open-source-app/blob/main/docs/fsrs-scheduling-logic.md).

## Ταυτοποίηση

- OTP μέσω email με το Cognito
- Cookies συνεδρίας του προγράμματος περιήγησης σε κοινό τομέα για τη φιλοξενούμενη εφαρμογή ιστού
- Αρχική ρύθμιση πράκτορα με OTP στο `auth.<domain>`, που επιστρέφει μακροχρόνιο ApiKey
- `AUTH_MODE=none` για τοπική ανάπτυξη
- `AUTH_MODE=cognito` για ταυτοποίηση όπως στην παραγωγή

## Μορφή της εγκατάστασης

- `app.<domain>` -> CloudFront + S3
- `api.<domain>` -> API Gateway + Lambda backend
- `auth.<domain>` -> API Gateway + υπηρεσία ταυτοποίησης σε Lambda
- Postgres στο AWS RDS

Ο κύριος τομέας (apex) μπορεί να παραμείνει σε ξεχωριστό ιστότοπο μάρκετινγκ. Αν είναι ελεύθερος κατά την αρχική ρύθμιση, η υποδομή μπορεί να τον ανακατευθύνει προσωρινά στο `app.<domain>`.

---
*[Δείτε τη μορφοποιημένη έκδοση HTML αυτής της σελίδας](<https://nibomo.com/el/docs/architecture/>)*

*Οι πράκτορες AI μπορούν να δημιουργήσουν λογαριασμό για τον χρήστη σε αυτήν την υπηρεσία ξεκινώντας με `GET https://api.nibomo.com/v1/`. Μετά τη ρύθμιση, μπορούν επίσης να συνδεθούν μέσω MCP στο `https://mcp.nibomo.com/mcp`.*

*Συμβουλή: προσθέστε `.md` σε οποιοδήποτε URL στο https://nibomo.com για να λάβετε μια καθαρή έκδοση της σελίδας σε Markdown.*