# OBEsoft Architecture Migration Record

Status: **implemented and verified**

This document records the completed repository reorganization and the checks required for future changes. It replaces the earlier draft, whose unsafe assumptions about SQLite migrations, public database storage, CSS merging, and FastAPI compatibility were corrected during implementation.

## Completed outcomes

- Established `public/` as the only web document root.
- Moved the SQLite database to private `storage/database/`.
- Preserved all legacy code, documentation, media, both CSS variants, and historical changelogs.
- Added environment-aware configuration and Git ignore rules for databases, secrets, backups, logs, and generated files.
- Added ordered database migrations tracked by both `schema_migrations` and `PRAGMA user_version`.
- Added users, roles, permissions, role-permission grants, course assignments, and audit logs without changing the existing `courses` schema or calculation data.
- Added secure sessions, password hashing, CSRF verification, course ownership checks, and server-side permissions.
- Added protected user-management and teaching-assignment APIs.
- Added default-enabled login, Teacher-only registration, email verification, password recovery, Google sign-in integration, and the administrator user-management page.
- Replaced raw WAL-file backup behavior with consistent SQLite backup and validated restore operations.
- Preserved the current frontend API paths and response envelopes.
- Kept the optional FastAPI backend operational through PHP-compatible aliases and the new public asset layout.
- Prevented FastAPI from starting when authentication is enabled so that it cannot bypass PHP RBAC.
- Added automated PHP, JavaScript, Python, preservation, database, backup/restore, and HTTP tests.

## Active layout

```text
OBEsoft-v2/
|-- public/
|   |-- index.php
|   |-- api/
|   |   |-- assignments.php
|   |   |-- auth.php
|   |   |-- google-login.php
|   |   |-- google-callback.php
|   |   |-- backup.php
|   |   |-- courses.php
|   |   |-- institution.php
|   |   `-- users.php
|   `-- assets/
|       |-- css/
|       |-- img/
|       `-- js/
|-- src/
|   |-- Auth/
|   |-- Database/
|   |-- Http/
|   |-- Repositories/
|   `-- Services/
|-- config/
|-- database/migrations/
|-- storage/
|   |-- database/
|   |-- backups/
|   |-- logs/
|   |-- sessions/
|   `-- test/
|-- tests/
|-- docs/
|-- legacy/
|-- backend/
|-- app.py
|-- run.bat
|-- run-python.bat
|-- requirements.txt
|-- .env.example
|-- .gitignore
`-- README.md
```

## Migration history

1. `001_initial_schema.php` safely adopts or creates the existing institution and courses schema.
2. `002_rbac_foundation.php` introduces the RBAC and auditing tables and seeds the three supported roles and their permission grants.
3. `003_account_lifecycle.php` adds verification, recovery, external identity, account-provider, session-revocation, and rate-limit storage.

Existing course rows are preserved. A `teacher_id` column was intentionally not added to `courses`: teacher access is many-to-many and offering-specific, so it is represented by `course_assignments`.

## Security model

Authentication is enabled by default. The first visit creates the initial administrator through the one-time setup screen. Public registration creates only Teacher accounts; Admin and Manager roles are granted from the protected administrator page. Email verification and recovery use private, expiring, one-time tokens.

The production deployment must:

1. Point its document root to `public/`, never the repository root.
2. Give the application process write access to `storage/` only where required.
3. Use HTTPS before enabling authentication.
4. Keep `.env`, databases, backups, and logs outside version control.
5. Use the PHP runtime when authentication is enabled.

## Required verification after future changes

Run:

```powershell
powershell -ExecutionPolicy Bypass -File tests/run.ps1
```

No structural, database, API, or calculation-related change should be accepted unless this suite passes. New calculation behavior should also add fixture-based expected-result tests before changing the corresponding formulas.

## Rollback material

The pre-migration source snapshot, SHA-256 inventory, and SQLite online backup are stored under `storage/backups/pre-restructure-20260920/`. This directory is ignored by Git and is intended for local recovery only.