# rubyazz/oku-ai architecture

> Architecture diagram of the GitHub repository rubyazz/oku-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rubyazz/oku-ai
- Repository: https://github.com/rubyazz/oku-ai

## Overview

OKU-AI is a modular Django learning platform with a React client. The visible user journey includes authenticated access to learning features and a review queue that can start a practice session; the broader product also covers diagnostics, mock exams, study planning, AI tutoring, and learner progress. Sampled source confirms review-queue UI behavior, payment-webhook subscription granting, and background notification flows. The README is empty, and most domain wiring was not sampled, so those capabilities are shown without speculative call chains.

Main entry points: [`apps/payments/services/webhooks.py`](https://github.com/rubyazz/oku-ai/blob/main/apps/payments/services/webhooks.py) (Payment webhooks), [`frontend/src/App.tsx`](https://github.com/rubyazz/oku-ai/blob/main/frontend/src/App.tsx) (App routes), [`frontend/src/features/reviews/reviews-page.tsx`](https://github.com/rubyazz/oku-ai/blob/main/frontend/src/features/reviews/reviews-page.tsx) (Review queue), [`apps/spaced_repetition`](https://github.com/rubyazz/oku-ai/tree/main/apps/spaced_repetition) (Spaced reviews)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner client"]
  node_app["App routes<br/>[App.tsx]"]
  node_reviews_ui["Review queue<br/>[reviews-page.tsx]"]
  node_learning_api["Learning client<br/>[learning.ts]"]
end

subgraph group_learning["Learning domains"]
  node_practice["Practice sessions"]
  node_exams["Mock exams"]
  node_diagnostics["Diagnostics"]
  node_mastery["Mastery progress"]
  node_reviews["Spaced reviews"]
  node_plans["Study plans"]
  node_curriculum["Curriculum search"]
  node_questions["Question bank"]
  node_review_records[("Review records<br/>[models.py]")]
end

subgraph group_platform["Platform services"]
  node_ai["AI tutoring"]
  node_accounts["Accounts"]
  node_authorization["Access control"]
  node_notifications["Notifications<br/>[notifications.py]"]
end

subgraph group_commercial["Commerce"]
  node_payment_webhooks["Payment webhooks<br/>[webhooks.py]"]
  node_subscriptions["Subscriptions<br/>[subscriptions.py]"]
  node_payment_records[("Payment records<br/>[models.py]")]
end

node_student(("Learner"))
node_external_provider(("Payment provider"))

node_student -->|"uses"| node_app
node_app -->|"routes to"| node_reviews_ui
node_reviews_ui -->|"requests queue"| node_learning_api
node_reviews -->|"reads due items"| node_review_records
node_payment_webhooks -->|"verifies delivery"| node_external_provider
node_payment_webhooks -->|"updates"| node_payment_records
node_payment_webhooks -->|"grants subscription"| node_subscriptions
node_notifications -->|"delivers notice"| node_student

click node_app "https://github.com/rubyazz/oku-ai/blob/main/frontend/src/App.tsx"
click node_reviews_ui "https://github.com/rubyazz/oku-ai/blob/main/frontend/src/features/reviews/reviews-page.tsx"
click node_learning_api "https://github.com/rubyazz/oku-ai/blob/main/frontend/src/lib/learning.ts"
click node_practice "https://github.com/rubyazz/oku-ai/tree/main/apps/practice"
click node_exams "https://github.com/rubyazz/oku-ai/tree/main/apps/mock_exams"
click node_diagnostics "https://github.com/rubyazz/oku-ai/tree/main/apps/diagnostics"
click node_mastery "https://github.com/rubyazz/oku-ai/tree/main/apps/mastery"
click node_reviews "https://github.com/rubyazz/oku-ai/tree/main/apps/spaced_repetition"
click node_plans "https://github.com/rubyazz/oku-ai/tree/main/apps/study_plans"
click node_curriculum "https://github.com/rubyazz/oku-ai/tree/main/apps/curriculum"
click node_questions "https://github.com/rubyazz/oku-ai/tree/main/apps/questions"
click node_ai "https://github.com/rubyazz/oku-ai/tree/main/apps/ai/services"
click node_accounts "https://github.com/rubyazz/oku-ai/tree/main/apps/accounts"
click node_authorization "https://github.com/rubyazz/oku-ai/tree/main/apps/authorization"
click node_notifications "https://github.com/rubyazz/oku-ai/blob/main/apps/notifications/services/notifications.py"
click node_review_records "https://github.com/rubyazz/oku-ai/blob/main/apps/spaced_repetition/models.py"
click node_payment_webhooks "https://github.com/rubyazz/oku-ai/blob/main/apps/payments/services/webhooks.py"
click node_subscriptions "https://github.com/rubyazz/oku-ai/blob/main/apps/subscriptions/services/subscriptions.py"
click node_payment_records "https://github.com/rubyazz/oku-ai/blob/main/apps/payments/models.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_reviews_ui,node_learning_api toneBlue
class node_practice,node_exams,node_diagnostics,node_mastery,node_reviews,node_plans,node_curriculum,node_questions,node_review_records toneAmber
class node_ai,node_accounts,node_authorization,node_notifications toneMint
class node_payment_webhooks,node_subscriptions,node_payment_records toneRose
class node_student,node_external_provider toneIndigo
```

## Components

### Learner client

- [App routes](https://github.com/rubyazz/oku-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Review queue](https://github.com/rubyazz/oku-ai/blob/main/frontend/src/features/reviews/reviews-page.tsx): `frontend/src/features/reviews/reviews-page.tsx`
- [Learning client](https://github.com/rubyazz/oku-ai/blob/main/frontend/src/lib/learning.ts): `frontend/src/lib/learning.ts`

### Learning domains

- [Practice sessions](https://github.com/rubyazz/oku-ai/tree/main/apps/practice): `apps/practice`
- [Mock exams](https://github.com/rubyazz/oku-ai/tree/main/apps/mock_exams): `apps/mock_exams`
- [Diagnostics](https://github.com/rubyazz/oku-ai/tree/main/apps/diagnostics): `apps/diagnostics`
- [Mastery progress](https://github.com/rubyazz/oku-ai/tree/main/apps/mastery): `apps/mastery`
- [Spaced reviews](https://github.com/rubyazz/oku-ai/tree/main/apps/spaced_repetition): `apps/spaced_repetition`
- [Study plans](https://github.com/rubyazz/oku-ai/tree/main/apps/study_plans): `apps/study_plans`
- [Curriculum search](https://github.com/rubyazz/oku-ai/tree/main/apps/curriculum): `apps/curriculum`
- [Question bank](https://github.com/rubyazz/oku-ai/tree/main/apps/questions): `apps/questions`
- [Review records](https://github.com/rubyazz/oku-ai/blob/main/apps/spaced_repetition/models.py): `apps/spaced_repetition/models.py`

### Platform services

- [AI tutoring](https://github.com/rubyazz/oku-ai/tree/main/apps/ai/services): `apps/ai/services`
- [Accounts](https://github.com/rubyazz/oku-ai/tree/main/apps/accounts): `apps/accounts`
- [Access control](https://github.com/rubyazz/oku-ai/tree/main/apps/authorization): `apps/authorization`
- [Notifications](https://github.com/rubyazz/oku-ai/blob/main/apps/notifications/services/notifications.py): `apps/notifications/services/notifications.py`

### Commerce

- [Payment webhooks](https://github.com/rubyazz/oku-ai/blob/main/apps/payments/services/webhooks.py): `apps/payments/services/webhooks.py`
- [Subscriptions](https://github.com/rubyazz/oku-ai/blob/main/apps/subscriptions/services/subscriptions.py): `apps/subscriptions/services/subscriptions.py`
- [Payment records](https://github.com/rubyazz/oku-ai/blob/main/apps/payments/models.py): `apps/payments/models.py`

### Other components

- **Learner**
- **Payment provider**

## Connections

- Learner → App routes: uses
- App routes → Review queue: routes to
- Review queue → Learning client: requests queue
- Spaced reviews → Review records: reads due items
- Payment webhooks → Payment provider: verifies delivery
- Payment webhooks → Payment records: updates
- Payment webhooks → Subscriptions: grants subscription
- Notifications → Learner: delivers notice