40227-vm/backend/docs/index.md

Backend Documentation Index

Start Here

• Repository working rules: ../../CLAUDE.md
• Backend architecture: backend-architecture.md
• Database schema: database-schema.md
• Error handling: error-handling.md

Read the repository rules first, then use the backend architecture document as the default development contract for backend work. Every product slice and entity has its own document following the per-slice template (Purpose / Slice Files by layer / API / Access Rules / Tenant Scope / Data Contract / Behavior / Tests / Related).

Architecture And Foundations

• backend-architecture.md: three-layer architecture (API -> BLL -> DAL), import direction, module-authoring factories.
• shared-crud-factories.md: the CRUD service/controller/router factories, repository helpers, and shared service helpers every generic-CRUD slice is built from.
• database-schema.md: generated table/column/relation reference.
• data-model-guide.md: read before adding any model/column or DB change — purpose, status, and reuse guidance (which slice/reserved table already covers a need, so you wire instead of duplicating).
• migrations-and-seeders.md: the Umzug runner, file conventions, and how to author a migration/seeder.
• error-handling.md: centralized AppError pipeline and error body shape.
• test-coverage.md: backend test runner, utilities, and current unit coverage.

Auth And Access

• auth-profile.md: sign-in, profile, GET /api/auth/me, OAuth, permission model.
• cookie-auth.md: HttpOnly cookie sessions and refresh rotation.
• permissions.md: the ${METHOD}_${ENTITY} permission catalog and enforcement.
• roles.md: the 11 first-class roles (scope, globalAccess) and role<->permission linkage.
• users.md: users entity, invitations, role policy, provisioning, and CSV bulk import.

Product Feature Slices

• audio-files.md: classroom-timer sound library (file/url/recipe kinds).
• campus-attendance.md
• campus-catalog.md: public campus records and branding.
• communications.md
• content-catalog.md
• frame-entries.md
• personality-quiz-results.md
• policy-documents.md: unified Safety Protocols + Handbook & Policies store and per-version acknowledgments.
• safety-quiz-results.md
• staff-attendance.md
• user-progress.md
• walkthrough-checkins.md
• zone-checkin.md: daily staff self-regulation check-in (campus-timezone "today" + nudge).

Generic CRUD Entity Slices

One document per entity (assembled from the shared CRUD factories; identical 9-endpoint surface — see shared-crud-factories.md).

• People: staff.md, organizations.md.
• Academics: classes.md, subjects.md, class_subjects.md, class_enrollments.md, academic_years.md, assessments.md, assessment_results.md, grades.md.
• Attendance: attendance_sessions.md, attendance_records.md.
• Scheduling: timetables.md, timetable_periods.md.
• Messaging: messages.md, message_recipients.md.
• Access: campuses.md (authenticated CRUD), roles.md.

Infrastructure Slices

• file.md: upload/download, storage backend, ownership notes.
• search.md: cross-entity search endpoint.
• email.md: transactional email senders and HTML templates.
• shared-crud-factories.md: shared CRUD building blocks.
• migrations-and-seeders.md: Umzug runner and conventions.