Edutrium Frontend — Overview & Tech Stack
Technical overview of the Edutrium frontend monorepo — architecture, packages, integrations, and AI development guidelines.
Repository Overview
| Property | Value |
|---|---|
| Project | Edutrium Platform – System Dashboard |
| Monorepo | Turborepo + pnpm |
| Apps | system-dashboard (Next.js 16 + React 19), student-portal (placeholder) |
| Shared Packages | @edutrium/api, @edutrium/auth, @edutrium/ui, @edutrium/i18n, @edutrium/typescript-config |
| Styling | Tailwind CSS 4 |
| Linting | Biome 2 |
| i18n | English, Arabic (RTL), Turkish |
| Total Commits | 440 |
| Weeks Covered | 13 |
| Date Range | 2025-12-28 → 2026-03-19 |
Lines of Code
Measured across all TypeScript / TSX / CSS source files, excluding
node_modules,.next,dist, and lock files.
| Area | Files | Lines |
|---|---|---|
apps/system-dashboard (app + features + components) |
~240 TSX + TS | 37,333 |
packages/ui (27+ UI primitives + DataGrid) |
~149 TS/TSX | 21,452 |
packages/api (OpenAPI client, React Query hooks) |
~40 TS | 9,083 |
packages/auth (better-auth integration, RBAC) |
~10 TS | 357 |
packages/i18n (i18n config, locale types) |
~5 TS | 220 |
| Total | ~389 source files | ~68,445 TS/TSX + 190 CSS = ~68,635 |
Note: The
packages/api/src/openapi-schema.tsfile alone accounts for a large portion of the API package lines — it is auto-generated from the OpenAPI spec viapnpm generate:api.
Integrations & Packages
Core Framework & Runtime
| Package | Version | Purpose |
|---|---|---|
next |
16.x | React meta-framework (App Router, RSC, Turbopack) |
react / react-dom |
19.x | UI runtime |
typescript |
5.9 | Static typing |
turbo |
2.x | Monorepo build orchestration |
pnpm |
10.x | Fast, disk-efficient package manager |
Authentication
| Package | Purpose |
|---|---|
better-auth |
Full-stack authentication (sessions, OAuth, roles) |
zod |
Schema validation for auth forms and API payloads |
API & Data Fetching
| Package | Purpose |
|---|---|
openapi-fetch |
Type-safe HTTP client generated from OpenAPI spec |
openapi-react-query |
Bridges openapi-fetch with TanStack Query |
openapi-typescript |
Generates TypeScript types from OpenAPI YAML/JSON |
@tanstack/react-query |
Server-state management, caching, mutations |
@tanstack/react-query-devtools |
Dev-time query inspector |
File Storage (Presigned Uploads)
| Integration | Notes |
|---|---|
| S3-compatible object storage (R2/S3) | Files are uploaded directly from the browser via presigned PUT URLs obtained from the backend (/presign, /presign/batch). No file content passes through the Next.js server. Hooks: usePresignedUpload, useBatchPresignedUpload. |
UI & Styling
| Package | Purpose |
|---|---|
tailwindcss |
4.x — utility-first CSS |
tw-animate-css |
Animation utilities for Tailwind |
radix-ui / @radix-ui/* |
Accessible, unstyled component primitives |
shadcn |
Copy-paste component scaffolding on top of Radix |
class-variance-authority |
Type-safe variant-based component styling |
clsx + tailwind-merge |
Conditional class composition |
lucide-react |
Icon set (always wrapped via <Icon> component) |
cmdk |
Command palette (⌘K) |
sonner |
Toast notifications |
next-themes |
Light/dark theme support |
Data Grid & Tables
| Package | Purpose |
|---|---|
@tanstack/react-table |
Headless table engine (sorting, filtering, pagination) |
@tanstack/react-virtual |
Virtual row rendering for large datasets |
@dnd-kit/core + sortable + modifiers |
Drag-and-drop row reordering |
Forms, Dates & Validation
| Package | Purpose |
|---|---|
react-hook-form |
Performant form state management |
@hookform/resolvers |
Integrates Zod schemas with react-hook-form |
zod |
Schema definitions and runtime validation |
react-day-picker |
Date picker calendar component |
@js-temporal/polyfill |
TC39 Temporal API (used for timezone-aware date formatting — replaces Date) |
date-fns |
Date utilities |
nuqs |
URL-bound query-string state (filters, active tab, pagination) |
react-select |
Async multi-select dropdowns |
Internationalisation
| Package | Purpose |
|---|---|
next-intl |
App Router-compatible i18n (en / ar RTL / tr) |
@lingual/i18n-check |
Lint missing or unused translation keys |
Export
| Package | Purpose |
|---|---|
jspdf + jspdf-autotable |
Client-side PDF export from DataGrid |
Dev Tools & CI
| Package | Purpose |
|---|---|
@biomejs/biome |
Linter + formatter (replaces ESLint + Prettier) |
husky |
Git pre-commit hooks |
vitest |
Unit test runner |
babel-plugin-react-compiler |
React 19 compiler transforms |
| GitHub Actions | CI: i18n check, Docker build, deploy |
AI-Assisted Development Guide
What AI Can Do Freely
These tasks are highly repetitive, follow established patterns, and carry low risk.
| Task | Example | Why it's safe |
|---|---|---|
| Duplicate / scaffold a new CRUD feature | Adding currencies from cities pattern |
All CRUD pages follow identical structure |
| Add a new form field component | GalleryUploadField, StringListField |
Strict contract (value/onChange, i18n label, Zod schema) |
| Add new i18n message keys | Translation strings | Pure data — no logic |
| Generate OpenAPI TypeScript types | pnpm generate:api |
Fully automated |
| Write Zod validation schemas | Form schemas | Structural, declarative |
| Scaffold DataGrid columns | Column definitions | Always the same shape |
| Add a new sidebar route / nav entry | RBAC route additions | Pure config |
| Translate UI strings to Arabic/Turkish | Message JSON files | No logic involved |
| Write unit tests for utility functions | date-formatters.ts helpers |
Pure functions with clear contracts |
What AI Can Do — But Needs Security Review
| Task | Risk | Mitigation |
|---|---|---|
| Presigned file upload flows | Wrong bucket, missing MIME validation, URL exposure | Review allowed MIME types, max size, URL expiry |
| Auth-gated routes / middleware | Missing permission check exposes admin pages | Verify can(resource, action) calls match RBAC matrix |
| PATCH forms (send only modified fields) | Missing extractModifiedFields sends full objects |
Ensure AI uses the existing utility |
| API endpoint wiring | Wrong HTTP verb, wrong path, wrong body | Cross-reference openapi-schema.ts |
Role-based UI visibility (<Can>) |
Showing admin controls to non-admin users | Pair UI hiding with server-side checks |
| URL state (nuqs) | Polluted query strings can expose internal IDs | Validate parsed values |
| i18n RTL layout (Arabic) | Flipped directions, broken icon mirroring | Manually test RTL render |
What AI Should NOT Generate (Human Only)
| Task | Why Not |
|---|---|
Authentication logic (packages/auth) |
Subtle mistakes create security vulnerabilities |
| OpenAPI schema changes | Auto-generated — changes belong in backend spec |
| RBAC permission matrix | Affects every role — must be designed deliberately |
| Environment variable handling | AI should never generate production secrets |
| Docker / CI pipeline changes | Supply-chain security implications |
| Database mutations via API | Incorrect data mutations can cause silent data loss |
| User-facing error messages with PII | Avoid leaking personal data in toasts/logs |