Skip to content
emergent engineering

System overview & repo tour

emergent is an education platform for language learning, built as a polyglot bun monorepo. The product surfaces are separate React + TanStack Router apps for learners, teachers, and admins, backed by a Bun API service and a shared domain/data core centred on Drizzle. Client data largely rides an offline-first sync rail (pgxsinkit over ElectricSQL + PGlite) rather than bespoke REST.

Repo tour

Section titled “Repo tour”

apps/

Section titled “apps/”
  • learner-web — the primary learner-facing React + TanStack Router app.
  • teacher-portal — teacher workflows: Offerings, Learning Units, Assessments, gradebook.
  • admin-console — operational/admin surface and deployment-validation tooling.
  • docs — end-user documentation site (Astro Starlight; Administer / Teach / Learn).
  • docs-eng — this site: internal engineering docs (Astro Starlight).
  • api — the Bun backend service.

packages/

Section titled “packages/”
  • ui — the shared Mantine v9 theme and wrapped components (single source of truth).
  • domain — domain types, validation, and the language-learning entities.
  • db — Drizzle schema and migrations.
  • offline-data — pgxsinkit and PGlite/Electric sync integration.
  • i18n, config, and other shared building blocks.

infra/

Section titled “infra/”

Kubernetes-native operations (no Dockerfiles / docker-compose in the app path):

  • charts/ — Helm charts (the emergent chart, Argo Workflows).
  • helmfile/ — Helmfile specs and per-environment values/.
  • k3s-deploy/ — bootstrap and install scripts for local k3s.
  • compose/ — podman-oriented compose specs for container-backed integration tests.
  • secrets/, utils/ — sops/age secret material and cluster utilities.

docs/ and tools/

Section titled “docs/ and tools/”

docs/ is the canonical engineering documentation tree (ADRs, architecture, conformance, design, integration, patterns, runbooks, backlog) — the source this site renders. tools/scripts/ holds the repo’s TypeScript operational scripts (test runners, conformance CLIs, the dev-channel switcher).

Key conventions

Section titled “Key conventions”
  • bun everywhere, never the npm CLI. Prefer package scripts (bun run typecheck, bun run lint, bun run format) over invoking tools directly.
  • oxlint + oxfmt for lint/format; turbo orchestrates the per-package tasks.
  • Drizzle objects over raw SQL — a strict tier hierarchy governs every DB expression (see the repo CLAUDE.md/AGENTS.md).
  • Canonical vocabulary — Offering, Learning Unit, Assessment, Person; never Course/Module/Lesson.
  • History is rebase-only; integration is linear.

For the reasoning behind decisions, read the ADRs and the architecture tree.