PRD

Balqalam is an open-source, multi-tenant K-12 school platform.

For shipped capabilities see MVP. For direction see Roadmap. For the commercial layer see Business model. The current commercial focus is the MENA-10 free pilot cohort; pipeline operations live in Leads.

Architecture

Stack

Surface area

For canonical counts of models, routes, dashboard pages, and tests, see MVP and Architecture.

Tenancy

Subdomain-based multi-tenancy resolved at the edge.

CopyProduction:   school.balqalam.com             →  /[lang]/s/school/...
Pilot tenant: kingfahd.balqalam.com          →  /[lang]/s/kingfahad/...
Preview:      tenant---branch.vercel.app      →  /[lang]/s/tenant/...
Development:  subdomain.localhost:3000        →  /[lang]/s/subdomain/...
Custom:       www.theirschool.com (CNAME)     →  Balqalam platform

Resolution flow:

1. Edge proxy.ts extracts subdomain from host.
2. Custom domains → canonical subdomain via Upstash Redis (custom-domain:${host}).
3. Internal rewrite to /[lang]/s/[subdomain]/... — /s/[subdomain] is internal only, never used in redirect() / Link href / router.push.
4. x-subdomain header set for downstream handlers.
5. getTenantContext() reads it and resolves schoolId for every Prisma query.

Single-language storage

Balqalam does not use bilingual columns. All content is stored in the school's chosen language with a lang field. Reads in another language go through Google Translate, cached in Translation. UI strings live in dictionaries (src/components/internationalization/dictionaries/); getText() (@/components/translation/display) is the canonical accessor.

Roles

Eight roles in prisma/models/auth.prisma:UserRole (DEVELOPER, ADMIN, TEACHER, STUDENT, GUARDIAN, ACCOUNTANT, STAFF, USER). Authorization via CASL abilities (@/lib/abilities) and route-level role gates. Full role surface and permissions in Authorization.

Functional scope

The 14-epic shipped state is in MVP. Next + Vision in Roadmap. Detail docs per epic live alongside in content/docs-en/. Block-level CLAUDE.md (src/components/<feature>/CLAUDE.md) documents per-feature implementation contracts.

A school can: accept applicants → register students → manage classes / sections / subjects / timetable → mark attendance (11 capture modes) → grade exams + generate report cards → collect fees (6 payment gateways) → message parents (in-app + email + WhatsApp) → run an LMS → manage library + transport. All on one platform with schoolId-scoped isolation.

Non-functional requirements

Performance

Security

• AES-256 at rest, TLS 1.3 in transit.
• Bcrypt (cost 12) passwords; JWT sessions; 2FA via TwoFactorToken + TwoFactorConfirmation.
• Brute-force protection via LoginAttempt audit + rate limits.
• RBAC on every route; multi-tenant isolation enforced server-side.
• Zod validation server-side; SQL-injection and XSS prevention.
• AuditLog retention with structured event types for sensitive mutations.
• 11 daily cron jobs for housekeeping.

Scalability

• Prisma connection pooling on Neon serverless PostgreSQL.
• Vercel serverless, stateless functions; aggressive outputFileTracingExcludes to stay under 300 MB.
• S3 + CloudFront for asset delivery.
• experimental.serverActions.bodySizeLimit: "10mb" for uploads.

Accessibility

• WCAG 2.1 AA targeted.
• Keyboard nav, screen-reader support, color contrast ≥ 4.5:1.
• Logical CSS properties — no ml-* / mr-*. RTL works without overrides.
• Semantic HTML — no hardcoded text-* / font-* Tailwind classes.

Compliance

Constraints

These rules apply to every contribution. Enforced by hooks, agents, and review gates.

• License — SSPL-1.0. Self-host free. Reselling Balqalam as a hosted service requires a commercial license.
• Multi-tenant safety. Every Prisma query includes schoolId (or the model is global and explicitly opts out). Isolation tests in tests/multi-tenant/.
• Single-language storage. Never bilingual columns; one lang field per row.
• Logical CSS only. ms-* / me-* / ps-* / pe-* — never ml-* / mr-* / pl-* / pr-*.
• No raw HTML primitives in components. Use shadcn ui/. No raw <button> / <input> / <select> in feature code.
• Mirror pattern. Routes import from src/components/<feature>/content.tsx. Canonical filenames per feature: content.tsx, actions.ts, queries.ts, authorization.ts, validation.ts, form.tsx, table.tsx, columns.tsx.
• One central .env. Never .env.local, .env.development, etc.
• Port 3000 in dev — always.
• pnpm tsc --noEmit before any build. Vercel build has typescript.ignoreBuildErrors: true to avoid OOM, so type-check is a separate gate.
• Internal rewrite safety. /s/[subdomain] is internal-only. UI uses clean tenant-relative paths.
• All UI text via dictionary keys. No hardcoded English or Arabic strings in components.

Subscription tiers

See Business model for pricing and revenue. See Sales for commercial process.

API and integrations

REST API v1

• OpenAPI 3.0 contract.
• API key auth with tiered rate limiting.
• Webhook events: student.enrolled, payment.received, grade.updated (full log in webhooks.prisma:ProcessedWebhookEvent).
• HMAC-SHA256 request signing; retry with exponential backoff.

SSO (Enterprise)

• SAML 2.0 — Okta, Azure AD, OneLogin.
• OAuth 2.0 — Google Workspace, Microsoft 365.
• SCIM for user provisioning.

Third-party connections (built or wired)

Stripe + bankak + tap + mobile-money + bank-transfer + cash, Plaid + Dwolla, Resend, Twilio, WhatsApp Evolution API, Google Translate, AWS S3 + CloudFront, Upstash Redis, Sentry, Mapbox + Leaflet, Anthropic + OpenAI + Groq.

Design system

Internationalization

See Translation for the full dictionary contract.

Development approach

• 1-week sprint cadence.
• Conventional commits, signed.
• Code review with at least one approver before merge to main.
• 80%+ coverage target on critical paths.
• Performance budgets (Lighthouse ≥ 90).
• 20% of sprint capacity reserved for tech debt.

Testing pyramid

Local DB workflow

Destructive Prisma operations (db execute, db push --accept-data-loss, migrate reset, DROP TABLE, TRUNCATE) are blocked by hooks. Use the Branch-Before-Touch protocol on Neon for risky DB ops. Never run pnpm db:seed directly — always pnpm db:seed:single <name>.

How to contribute

1. Read Get started for the local setup.
2. Skim Architecture and Pattern for conventions.
3. Pick a Roadmap "Next" item or open a feature issue.
4. Follow the mirror pattern + the constraints above.
5. The Claude harness in .claude/ (50 agents, 47 commands, 16 skills) is wired to enforce most rules automatically — pnpm dev plus the project's CLAUDE.md is enough.

The OSS contribution model — including how time invested converts to recognition or revenue share — lives in Shared economy.

AGENTS.md is currently AGENTS.md.draft at the repo root; graduating it to AGENTS.md is tracked in Roadmap.

See also

• Pilot — MENA-10 free pilot cohort (current commercial focus)
• GTM — three-phase go-to-market
• Sales — B2B process
• Leads — pipeline operations
• MVP — 14-epic shipped state with maturity badges
• Roadmap — Next milestones and Vision
• Architecture — system design and patterns
• Pattern — code conventions
• Translation — i18n contract
• Shared economy — OSS contribution and value-sharing
• Business model — pricing, tiers, ARR projections
• Get started — local setup