Metatron_Student_ERP/PHASE_12_RELEASE_READINESS_REPORT.md

# Phase 12: Metatron Student ERP — Deployment and Mobile App Release Preparation Report

**Date:** October 15, 2026  
**Auditor/Release Engineer:** Antigravity Autonomous Agent  
**Environment:** Backend: Odoo 19 Community Edition (`metatron_academic`) | Database: PostgreSQL 15 (`metatron_aca_erp`) | Mobile App: Flutter (`flutter_app/`)  
**Current Branch:** `main`

---

## 1. Baseline Branch, Commit, Working-Tree Status, and Unpushed Commits

- **Active Branch:** `main`
- **Release Preparation HEAD Commit:** `921ddc9`
  - Message: `chore(release): configure deployment architecture, environment security, and release signing`
- **Preceding Audit Baseline Commit:** `e5d3fdc` (`fix(education): harden production readiness and access controls`)
- **Remote Tracking:** `origin/main` (at `a20b916` / `mobile_api`)
- **Unpushed Commits:** **9 commits ahead of `origin/main`** (no automatic push performed):
  1. `921ddc9` — `chore(release): configure deployment architecture, environment security, and release signing`
  2. `e5d3fdc` — `fix(education): harden production readiness and access controls`
  3. `1277f7a` — `feat(education_student): add secure profile and document management`
  4. `ff2d790` — `feat(education_finance): integrate student fees and payment tracking`
  5. `bce010f` — `feat(education_announcements): integrate student notices and notifications`
  6. `1d40349` — `feat(education_timetable): complete schedule management and mobile integration`
  7. `232e22e` — `feat(education_attendance): complete attendance workflow and mobile integration`
  8. `2b4b4ae` — `feat(education_exam): implement marks entry, grading, and secure result publication`
  9. `69d69f0` — `feat(flutter_app): initialize Phase 4 Flutter mobile application with Riverpod, Dio, GoRouter, Material 3, and live Odoo session auth`
- **Working Tree Status:** Clean (all release preparation configs and manifests tracked/committed; report file generated).

---

## 2. Security and Configuration Findings

1. **Root Repository Hygiene:**
   - **Finding:** The root `.gitignore` only ignored `.pyc` and `.DS_Store`. Local database dumps, private keys, `.env` files, and keystores were vulnerable to accidental tracking.
   - **Remediation:** Hardened `.gitignore` to strictly ignore `.env*`, `*.dump`, `*.sql`, `*.tar.gz`, `*.key`, `*.pem`, `*.p12`, `*.jks`, `*.keystore`, `key.properties`, and build artifacts.
2. **API Endpoint & Host Hardcoding:**
   - **Finding:** `ApiConfig` previously fell back to `http://localhost:10008` even in release builds if `--dart-define=API_BASE_URL` was omitted.
   - **Remediation:** Implemented `AppEnvironment` (`development`, `staging`, `production`). In production mode, fallback to localhost is prohibited; requests fail cleanly with a structured `NOT_CONFIGURED` exception prompting the operator or user to set the API endpoint in Settings.
3. **HTTPS Enforcement:**
   - **Finding:** Release builds could theoretically connect over unencrypted cleartext HTTP if an insecure URL was supplied.
   - **Remediation:** Added Android Network Security Configuration (`res/xml/network_security_config.xml`) that disallows cleartext HTTP traffic across all domains by default, permitting HTTP only for local loopbacks (`localhost`, `10.0.2.2`) during debug/development.
4. **Credential Scanning:**
   - **Finding:** Verified all tracked source code in `addons/` and `flutter_app/`. No actual production private keys, production passwords, or third-party secret tokens are committed. Only field schemas and mock fallbacks for unit tests exist.
5. **Debug Output Sanitization:**
   - **Finding:** `developer.log` and request interceptors in `ApiClient` are strictly gated with `if (kDebugMode)`, ensuring no sensitive student profiles, session tokens, or transaction payloads are emitted into device system logs in release builds.

---

## 3. Backend Deployment Requirements

### Architecture Overview
The production deployment decouples services into three tiers:
1. **Edge Reverse Proxy (Nginx/Traefik):** Handles TLS 1.3 / HTTPS termination, rate limiting, request buffering, and static caching.
2. **Application Tier (Odoo 19 Community):** Runs in multiprocessing worker mode (`workers = 5`), with separated longpolling port 8072 for websocket events.
3. **Database Tier (PostgreSQL 15):** Placed on an internal Docker bridge network with no external port exposure.

### Key Deployment Files Created
- **`deploy/docker-compose.prod.yml`**: Production compose configuration with container health checks, log rotation (`json-file`, max 50MB x 5), internal network isolation, and environment-driven credentials.
- **`deploy/odoo.prod.conf`**: Hardened Odoo configuration with `list_db = False` (disabling database manager), `proxy_mode = True`, memory soft/hard limits, and CPU limits.
- **`deploy/nginx/metatron_erp.conf`**: Production Nginx configuration with HTTP-to-HTTPS 301 redirection, HSTS, security headers, 25MB body limit for student uploads, and WebSocket proxying.
- **`deploy/.env.example`**: Environment variable template for database credentials, domain names, and worker counts.

---

## 4. Backup and Recovery Instructions

A standalone automated utility is established at `deploy/backup_restore.sh`.

### Manual Backup Commands
```bash
# 1. Database backup (compressed custom format)
docker exec -t metatron_academic_db pg_dump -U odoo -Fc metatron_aca_erp > metatron_aca_erp_$(date +%Y%m%d_%H%M%S).dump

# 2. Filestore archive (attachments, student photos, certificate PDFs)
docker exec metatron_academic tar -czf - -C /var/lib/odoo/filestore metatron_aca_erp > filestore_metatron_aca_erp_$(date +%Y%m%d_%H%M%S).tar.gz
```

### Automated Utility Usage
```bash
# Full backup (creates dump, tar.gz archive, and SHA256 checksums):
./deploy/backup_restore.sh backup /path/to/backup_destination

# Verification of backup archives:
./deploy/backup_restore.sh verify /path/to/backup.dump /path/to/filestore.tar.gz

# Controlled restore to an isolated staging database:
./deploy/backup_restore.sh restore /path/to/backup.dump /path/to/filestore.tar.gz metatron_aca_erp_staging
```

*Verification test: Verified against live container `metatron_academic_db` and `metatron_academic`. Successfully generated valid 7.26 MB database dump and 15.18 MB filestore archive.*

---

## 5. Development, Staging, and Production API Configuration

The mobile app supports dynamic compile-time environment flags via `--dart-define`:

| Environment | Build Flag | Target URL Example | Cleartext Permitted |
|---|---|---|---|
| **Development** | Default (no flag) | `http://10.0.2.2:10008` (Android) / `http://localhost:10008` | Yes (Emulator loopback) |
| **Staging** | `--dart-define=ENVIRONMENT=staging --dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu` | `https://staging-erp.yourdomain.edu` | No |
| **Production** | `--dart-define=ENVIRONMENT=production --dart-define=API_BASE_URL=https://erp.yourdomain.edu` | `https://erp.yourdomain.edu` | No (HTTPS enforced) |

### Runtime Fallback & Settings Screen
If built without compile-time URL definitions or when connecting to a local campus network server, students or testing personnel can navigate to **Settings Screen -> API Server Address** and configure the custom base URL directly in the app.

---

## 6. Android Build and Signing Instructions

### Package & Configuration Summary
- **Package Name / Application ID:** `in.metatroncube.metatron_student_erp`
- **Application Label:** `Metatron Student ERP`
- **Min SDK:** 21 (Android 5.0 Lollipop)
- **Target SDK:** 34 (Android 14)
- **Version:** `1.0.0+1` (defined in `pubspec.yaml`)
- **Permissions Declared:**
  - `android.permission.INTERNET`
  - `android.permission.ACCESS_NETWORK_STATE`
- **Network Security Config:** `flutter_app/android/app/src/main/res/xml/network_security_config.xml`

### Production Keystore Configuration
1. Generate release keystore (keep outside git repository):
   ```bash
   keytool -genkey -v -keystore ~/metatron-release-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias metatron_release
   ```
2. Create `flutter_app/android/key.properties` from template:
   ```bash
   cp flutter_app/android/key.properties.example flutter_app/android/key.properties
   ```
3. Populate with your private credentials:
   ```properties
   storePassword=your_keystore_password
   keyPassword=your_key_password
   keyAlias=metatron_release
   storeFile=/absolute/path/to/metatron-release-keystore.jks
   ```
   *(Note: `build.gradle.kts` automatically loads `key.properties` when present, and safely defaults to debug signing for internal QA if absent).*

### Release Build Commands
```bash
cd flutter_app

# 1. Google Play Store Release (Android App Bundle - AAB):
flutter build appbundle --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu

# 2. Direct Distribution / Internal Staging QA (Split Per-ABI APKs):
flutter build apk --release --split-per-abi \
  --dart-define=ENVIRONMENT=staging \
  --dart-define=API_BASE_URL=https://staging-erp.yourdomain.edu
```

---

## 7. iOS Build and Signing Instructions

### Package & Configuration Summary
- **Bundle Identifier:** `in.metatroncube.metatronStudentErp`
- **Display Name:** `Metatron Student ERP`
- **Deployment Target:** iOS 12.0+
- **Privacy Usage Descriptions:**
  - `NSPhotoLibraryUsageDescription`: Required for uploading student profile photos and verification certificates.
  - `NSCameraUsageDescription`: Required for capturing physical identity documents and verification photos.
- **App Transport Security (ATS):** Strict HTTPS enforcement by default.

### Archiving and App Store Connect Submission Steps
1. Open the iOS workspace in Xcode:
   ```bash
   open flutter_app/ios/Runner.xcworkspace
   ```
2. In **Signing & Capabilities**, select your Apple Developer Team and Provisioning Profile.
3. Build the release archive from CLI or Xcode:
   ```bash
   cd flutter_app
   flutter build ipa --release \
     --dart-define=ENVIRONMENT=production \
     --dart-define=API_BASE_URL=https://erp.yourdomain.edu
   ```
4. Upload to App Store Connect / TestFlight:
   ```bash
   xcrun altool --upload-app --type ios -f build/ios/ipa/*.ipa --apiKey <API_KEY> --apiIssuer <ISSUER_ID>
   ```

---

## 8. Test and Build Results

### Automated Test Matrix
| Test Suite | Command | Result | Notes |
|---|---|---|---|
| **Flutter Static Analysis** | `flutter analyze` | **PASSED** (0 issues) | Strict type checking & zero lints |
| **Flutter Unit & Widget Tests** | `flutter test` | **PASSED** (64 / 64 passed) | Full coverage of UI widgets, providers, and state models |
| **Flutter Live Integration** | `flutter test test/live_odoo_integration_test.dart` | **PASSED** (12 / 12 passed) | End-to-end auth, profile, timetable, exams, fees, documents, certificates |
| **Odoo Backend Automated Tests** | `odoo --test-tags /education_*` | **PASSED** (70 / 70 passed) | 0 failed, 0 errors across all 8 modules |
| **Flutter Web Release Build** | `flutter build web --release` | **PASSED** (`✓ Built build/web`) | Verified tree-shaking and production compilation |
| **Android Release Build** | `flutter build apk --release` | **ENVIRONMENT-BLOCKED** | Host machine lacks local Android SDK toolchain |
| **Android App Bundle** | `flutter build appbundle --release`| **ENVIRONMENT-BLOCKED** | Host machine lacks local Android SDK toolchain |
| **iOS Release Archive** | `flutter build ipa --release` | **ENVIRONMENT-BLOCKED** | Host machine lacks full Xcode developer installation & CocoaPods |

---

## 9. Required Privacy Policies and Store Submission Prerequisites

### Play Store & App Store Compliance Checklist
1. **Privacy Policy URL:**
   - Must be hosted publicly (e.g. `https://yourdomain.edu/privacy-policy`).
   - Must state that student personal data (name, email, phone, enrollment ID) is collected exclusively for educational record administration and is not shared with third-party advertisers.
2. **Account Deletion / Request Policy:**
   - App Store and Play Store require providing students an option or URL to request account closure or data rectification through the institution's registrar office.
3. **Data Safety Form (Google Play Console):**
   - Personal info: Name, email, student ID collected for app functionality.
   - Financial info: Fee payment records (no credit card details stored on-device).
   - Photos and documents: Uploaded exclusively for institutional identity verification.
   - Encryption in transit: Yes (HTTPS/TLS 1.3).
4. **App Store Review Demo Credentials:**
   - Provide active demo credentials (`demo.student`) in the App Store Review Information notes.

---

## 10. Outstanding Blockers and Recommended Next Actions

### Blockers Before Public Release
1. **Production Domain & SSL Certificates:**
   - Real institutional domain (e.g. `erp.yourdomain.edu`) and valid Let's Encrypt / commercial SSL certificate are required.
2. **CI/CD Signing Environment:**
   - Android release keystore (`key.properties`) must be provisioned in the CI/CD secret manager (GitHub Actions / GitLab CI).
   - Apple Developer Team membership and distribution certificate must be linked in Xcode.
3. **Odoo Database Master Password:**
   - Replace placeholder master password in `deploy/odoo.prod.conf` with a securely vaulted secret.

---

## 11. Exact Commands for Eventual Deployment and Release

### Staging Deployment (Backend)
```bash
# 1. Clone repository to staging server
git clone <REPO_URL> metatron_erp && cd metatron_erp

# 2. Configure environment
cp deploy/.env.example deploy/.env
# Edit deploy/.env with staging database password and domain

# 3. Launch staging containers
docker compose -f deploy/docker-compose.prod.yml --env-file deploy/.env up -d

# 4. Restore sanitized database backup
./deploy/backup_restore.sh restore /path/to/staging_backup.dump /path/to/filestore.tar.gz metatron_aca_erp
```

### Production Release (Mobile)
```bash
cd flutter_app

# Android App Bundle for Google Play
flutter build appbundle --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu

# iOS IPA for App Store / TestFlight
flutter build ipa --release \
  --dart-define=ENVIRONMENT=production \
  --dart-define=API_BASE_URL=https://erp.yourdomain.edu
```

---
*Phase 12 Deployment and Mobile App Release Preparation complete. Awaiting user review and authorization.*