Axioma Learn

Axioma Learn is an early-stage learning workspace for students, educators, and institution administrators. It brings classes, coursework, file submissions, grading, and notifications into one application, with a longer-term goal of adding academic AI assistance grounded in course context.

The repository contains a TypeScript monorepo with a web frontend, an application API, shared domain contracts, and a database schema. The original JSX concept remains as a design reference; it is separate from the application in apps/.

Important

This is a development implementation with demo identity and fallback data. Authentication, tenant-safe authorization, AI assistance, and LMS imports are not complete production features.

What the source implements

Workspace	Current functionality
Student	Home summary, class directory, coursework details, file submission as draft or submitted work, submission history, and a notification inbox with mark-as-read actions.
Educator	Dashboard, review queue, class directory, coursework and submission views, grading and feedback actions, and a notification inbox.
Admin	Institution shell and a file moderation queue with status overrides and rescan requests. Institution and integration management screens are placeholders.

The API includes database-backed reads and mutations for these workflows, audit events, S3 upload/download URL signing, and Redis-backed file scan jobs. Several read endpoints return sample data when database reads fail or demo records are unavailable, so a populated screen does not necessarily mean the database is connected.

Submission workflow

1. A student selects a file on a coursework page.
2. A web server action requests a signed upload URL from the API, uploads the file to S3, and records its metadata and submission status through the API.
3. The API marks the file as pending scan, records an audit event, and queues a scan when Redis is configured. Otherwise, the file remains available for manual moderation.
4. The scan worker updates the moderation status and creates notifications for the student and educator.
5. Educators review submissions and record grades or feedback; administrators can override moderation decisions or request another scan.

The current scanner (stub_rules_v1) checks filenames, MIME types, and storage keys. It does not inspect file contents for malware.

Architecture

Location	Responsibility
apps/web	Next.js 15, React 19, and Tailwind CSS 4 frontend; shared app shell, server-rendered pages, API helpers, and server actions.
apps/api	NestJS 10 API for student, educator, admin, auth, storage, notifications, and health routes. Also runs the BullMQ scan worker.
packages/domain	Shared TypeScript models and Zod schemas for sessions, classes, coursework, submissions, moderation, and notifications.
packages/db	Prisma schema, generated client, and sample-data seed for PostgreSQL.
packages/ui	Shared theme tokens.
packages/ai	Study Buddy context type and system intent; no model execution pipeline yet.
packages/integrations	LMS adapter interface; no implemented import connector yet.
infra/aws/terraform	S3 storage and IAM provisioning, including encryption, versioning, and lifecycle configuration.
docs	Product goals, architecture direction, development notes, and planned work.

pnpm workspaces and Turborepo coordinate the packages. The web app calls the API under /api; the API uses Prisma for relational data, S3 for submission files, and BullMQ/Redis for background scan processing.

The database models institutions, users, classes, coursework, resources, submissions, office-hour slots and bookings, audit events, AI interactions, and notifications. A schema model alone does not imply a completed user-facing workflow.

Local development

Prerequisites: Node.js 22 or newer, pnpm 10 (the repository pins 10.8.0), and Docker with Compose for PostgreSQL and Redis.

From the repository root, create local environment files if they do not already exist. In PowerShell:

Copy-Item apps/api/.env.example apps/api/.env
Copy-Item apps/web/.env.example apps/web/.env.local
$env:DATABASE_URL = "postgresql://postgres:postgres@localhost:5432/axioma_learn"

The shell variable supplies the database URL to the database package commands; the API reads its own .env. Then run:

pnpm install
pnpm docker:up
pnpm db:generate
pnpm db:push
pnpm db:seed
pnpm dev

Wait until PostgreSQL is ready before running db:push. Use a local development database: db:push applies the schema, and db:seed writes sample academic records for North River University, including Cellular Biology and Applied Statistics classes.

Surface	Local URL
Platform overview	http://localhost:3000
Student workspace	http://localhost:3000/student
Educator workspace	http://localhost:3000/educator
Admin workspace	http://localhost:3000/admin
API health	http://localhost:4000/api/health

NEXT_PUBLIC_API_URL defaults to http://localhost:4000; omit /api because the web helpers append it. Compose exposes PostgreSQL on port 5432 and Redis on 6379.

File uploads additionally require S3_BUCKET, S3_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY in the API environment. The API example includes optional endpoint, encryption, prefix, and signed-URL settings. Compose does not provision object storage; see the storage infrastructure README.

Useful commands

Command	Purpose
pnpm dev:all	Start the Compose services and both development apps.
pnpm dev:web / pnpm dev:api	Start one application.
pnpm typecheck	Check TypeScript across the workspace.
pnpm build	Build the workspace packages and applications.
pnpm format:check	Check repository formatting with Prettier.
pnpm db:studio	Open the database browser.
pnpm docker:down	Stop the local Compose services.

pnpm setup installs dependencies, starts Compose, and generates Prisma's client; it does not apply the schema or seed the database. Test scripts currently print placeholders, and several package lint scripts do the same.

Current limits and planned work

• Identity and access: /api/auth/session returns a demo session. Setting WorkOS credentials changes the reported configuration, but does not implement login or session verification. Active controllers still select demo users by role rather than an authenticated actor.
• AI: Study Buddy and educator AI are product goals. The AI package currently defines context and intent only.
• Integrations: LMS imports are interface definitions. Calendar and integration screens are placeholders; office-hour records exist without a complete booking interface.
• File safety: Scan orchestration and moderation are implemented, but the scanner is a metadata-based stub.
• Verification: Automated application tests have not been implemented. The health route reports API process status, not readiness of the database, queue, or storage.

Further reading

• Product goals and feature breakdown
• Architecture direction and domain model notes
• Development notes and external service setup
• Roadmap

Some supporting documents still describe the original prototype or future architecture. Treat them as design direction; the implementation overview above describes the current source.