# Nujoom — Arabic Learning Platform for Children

نجوم التعلم — "stars of learning." An Arabic-language learning platform for children,
with a parent dashboard, a child mode, an admin panel, and an AI tutor the child can talk
to.

Arabic-first, which here means RTL is the source layout rather than a stylesheet flip
applied at the end. Every screen was designed in Arabic and reads in Arabic; there is no
English original underneath it.

## The relay

The interesting engineering problem wasn't the curriculum. It was that the model API is
**blocked from Syria outright** — not rate-limited, not degraded, refused at the network
level. A tutor that returns an error to a seven-year-old is not a feature.

So in the first version, requests didn't go to the model provider. They went to a small
Cloudflare Worker that forwarded them and returned the response. The Worker ran on
Cloudflare's edge, which is reachable, and the API key lived there rather than in the client
or the app server.

This is the shape of a lot of my work: the constraint isn't in the spec, it's in the
country, and the design has to absorb it without the user ever finding out. A child using
the app has no idea there's a hop in the middle.

## Structure

Two halves, kept apart on purpose.

The **frontend** is plain HTML, CSS and JavaScript — home, login, the parent dashboard,
the child dashboard, the admin panel, a shared `api.js`, and an `activities/` directory for
the exercises themselves. No framework.
For a set of pages that are mostly big touch targets and one chat panel, a build step
would have bought nothing and cost a toolchain to maintain.

The **backend** is Hono and TypeScript on Cloudflare Workers, with the data in D1. Email and
password auth with JWTs, parents create child profiles under their own account, and the
admin surface is gated behind a separate internal API key rather than a role bit on a user
row — a compromised parent account should not be able to become an admin.

`JWT_SECRET`, the admin key and the Groq key are secrets on the Worker, and the same Worker
serves the frontend as static assets.

## The move to Workers

The first version was Node.js and Express over SQLite, in Docker. It ran at home,
and power cuts emptied its database twice. On 2026-08-17 I ported
the backend to Workers and D1. The backend now runs on Cloudflare too, so it calls Groq
itself and the separate relay hop is gone. The repo's `main` still has the Express version;
the port is on the `feat/cloudflare-workers-migration` branch.

## Notes on the Arabic

Small things that only show up when Arabic is the source language rather than a
translation target:

- `start` and `end` throughout instead of `left` and `right`, so nothing has to be
  mirrored by hand.
- Arabic-Indic digits (٠–٩) wherever a number is user-facing. A child learning to count
  in Arabic should see the numerals they're learning.
- Mixed-direction strings — an English product name inside an Arabic sentence — need
  explicit isolation or the punctuation ends up on the wrong side.

## Stack

Hono and TypeScript on Cloudflare Workers, D1, and Groq for the model. Before August 2026:
Node.js, Express, SQLite, Docker and a Cloudflare Worker relay.
