# TemseeEdu — V1 Product Requirements Document
**Version:** 3.0 (Updated — Dual Deployment + Plugin System)
**Author:** Linxford / Temsee
**Status:** Active Development Target

---

## 1. What We're Building (And What We're Not)

The vision document covers 30+ modules. This PRD covers **only what ships as V1**,
plus the plugin architecture that future modules will be delivered through.

The goal of V1 is simple:

> Win 3–5 paying schools. Deliver a working product. Generate recurring revenue. Learn from real deployments.

The core ships first. Plugins expand it.

---

## 2. Product Summary

**TemseeEdu** is a modern, modular school digital platform for Ghanaian and African
educational institutions. The core platform handles the essentials. Plugins extend it
based on what each school actually needs.

**Tagline:** Modern Digital Infrastructure for African Schools.

**V1 Core Delivers:**
- A premium school website (CMS-powered, no code needed)
- Online admissions system
- Student & parent portal
- Announcements & communication
- School admin dashboard
- Plugin engine (foundation for all future modules)

---

## 3. Deployment Models

Research into the Ghanaian school software market confirms the market is split.
Competitors like Smart School Manager and Edutrack Ghana market "pay-once lifetime license"
as their primary selling point. Academic research on Ghanaian tertiary institutions confirms
that loss of data control and distrust of third-party cloud providers are real, documented
barriers to cloud adoption in Ghana.

TemseeEdu ships in **two commercial editions** from day one, built from the same codebase.

---

### Edition A — TemseeEdu Cloud (SaaS)

**Who it's for:** Private schools, well-funded institutions, schools with no IT staff.

**How it works:**
- School gets a branded subdomain: `schoolname.temseeedu.com`
- Temsee hosts and manages everything
- School pays monthly or annually
- Updates, security, backups handled by Temsee
- Code never leaves Temsee's server — no encoding tool needed
- Plugins purchased and activated instantly from the admin panel

**Billing model:**

| Plan | Monthly | Annual (save 15%) | Included |
|------|---------|-------------------|---------|
| Starter | GHS 500 | GHS 5,100 | CMS + Admissions + 50 students |
| Growth | GHS 800 | GHS 8,160 | Everything + Portals + Comms + 300 students |
| Institution | GHS 1,500 | GHS 15,300 | Everything + Unlimited + SMS + Priority support |

**One-time setup fee:**
- Starter: GHS 1,500
- Growth: GHS 2,500
- Institution: GHS 4,000

---

### Edition B — TemseeEdu School Edition (Self-Hosted Licensed)

**Who it's for:** Government/public SHS, budget-conscious private schools, schools with
their own servers, institutions that require full data control.

**How it works:**
- School purchases a license key (one-time)
- Temsee installs the software on the school's server
- Encoded with SourceGuardian before delivery
- License key validates on boot — phones home to Temsee license server
- Plugins purchased separately, delivered as encoded zip files

**Why SourceGuardian over IonCube:**

| | IonCube | SourceGuardian |
|--|---------|----------------|
| PHP 8.3 support | Partial | Native, full support |
| Laravel 11 compatibility | Works with issues | Works cleanly |
| Obfuscation strength | Moderate | Stronger |
| Price | ~$499 one-time | ~$299/year |
| Modern PHP handling | Weaker | Better |

**Billing model:**

| License Type | Price | Included |
|-------------|-------|---------|
| Single School | GHS 8,000 | Full V1 core, 1 domain |
| Institution (500+ students) | GHS 12,000 | Full V1 core, 1 domain, priority setup |
| Multi-Branch | GHS 18,000 | Up to 3 campuses, 1 license |

**Annual support & updates contract:**
- Basic: GHS 1,500/year (updates + email support)
- Priority: GHS 2,500/year (updates + phone/WhatsApp + 2 training sessions)

**Installation & setup fee:** GHS 1,500–2,000 one-time

---

## 4. Plugin System

This is the most important architectural decision in TemseeEdu.
The core platform is lean and ships fast. Plugins are how TemseeEdu grows revenue
per school over time without bloating the base product.

### Philosophy

The plugin system must feel like **"scalable expansion"** — not **"missing features."**

Every school gets a fully working platform out of the box. Plugins add capabilities
schools choose when they need them. No core feature is hidden behind a plugin.

Bad plugin culture (what we avoid):
- Charging for basic buttons
- Crippling the core so plugins feel mandatory
- Confusing licensing per plugin
- Plugins that break the core on update

Good plugin culture (what we build):
- Plugins add genuinely new capability
- Clean enable/disable from admin panel
- Each plugin is independently licensed and versioned
- Plugins degrade gracefully if disabled (no data loss)

---

### Plugin Architecture (Laravel Modules)

We use **nWidart/laravel-modules** as the plugin foundation.
Each plugin is a self-contained Laravel module with its own:
- Routes
- Controllers
- Models
- Migrations
- Views (Blade)
- Filament resources
- Config
- Service Provider

```
app-modules/
├── Hostel/
│   ├── Config/
│   ├── Database/Migrations/
│   ├── Http/Controllers/
│   ├── Models/
│   ├── Providers/HostelServiceProvider.php
│   ├── Resources/ (Filament)
│   ├── Routes/
│   ├── Views/
│   └── module.json
├── Transport/
├── Library/
├── Payroll/
├── CBT/
├── ELearning/
├── Accounting/
├── Inventory/
└── Alumni/
```

Each `module.json` declares:
```json
{
  "name": "Hostel",
  "alias": "hostel",
  "version": "1.0.0",
  "requires_core": "1.0.0",
  "requires_plan": "growth",
  "license_required": true,
  "author": "Temsee",
  "description": "Hostel and boarding management for schools"
}
```

---

### Plugin Registry & Marketplace

**Cloud Edition:**
Schools browse and activate plugins from within the admin panel.

```
/admin/plugins               → Plugin marketplace (browse all available)
/admin/plugins/{slug}        → Plugin detail + pricing
/admin/plugins/{slug}/buy    → Purchase flow (Paystack/MoMo)
/admin/plugins/installed     → Manage installed plugins
```

Each plugin card shows:
- Plugin name + icon
- What it does (2-line description)
- Price (one-time or monthly add-on)
- Compatible plans
- Install / Activate / Deactivate button

**School Edition:**
Plugins are purchased from `temseeedu.com/plugins` and delivered as
an encoded zip file with a plugin-specific license key.

Installation flow:
1. School purchases plugin online
2. Receives encoded zip + plugin license key via email
3. Uploads zip in Admin → Plugins → Install
4. Enters plugin license key to activate
5. Plugin runs migrations automatically
6. Plugin appears in admin sidebar

---

### Plugin License System

Each plugin has its own license key — separate from the main system license.

```sql
-- On License Server
plugin_licenses (
  id,
  plugin_slug,           -- e.g. 'hostel', 'cbt', 'library'
  school_license_id,     -- links to parent school license
  license_key,           -- UUID, unique per plugin per school
  status,                -- active / suspended / expired
  issued_at,
  expires_at,            -- null = lifetime
  created_at
)
```

Plugin license verification (on plugin boot):

```php
// Each plugin's ServiceProvider calls this on register
class HostelServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton('hostel.license', function () {
            return PluginLicenseManager::verify('hostel');
        });
    }

    public function boot(): void
    {
        if (!$this->app->make('hostel.license')->isValid()) {
            // Plugin routes not registered
            // Filament resources not loaded
            // Migrations run but features locked
            return;
        }

        $this->loadRoutesFrom(__DIR__.'/../Routes/web.php');
        $this->loadMigrationsFrom(__DIR__.'/../Database/Migrations');
        // Register Filament resources...
    }
}
```

**Key rule:** Even if a plugin is disabled or its license expires,
its database tables remain intact. Data is never deleted on deactivation.
The school can reactivate and all data is still there.

---

### Plugin Pricing Model

**Cloud Edition — Add-on pricing (monthly):**

| Plugin | Monthly Add-on | One-Time (School Edition) |
|--------|---------------|--------------------------|
| Results & Grading | GHS 150 | GHS 1,500 |
| Attendance | GHS 100 | GHS 1,000 |
| Online Fee Payments | GHS 200 | GHS 2,000 |
| Library Management | GHS 100 | GHS 1,000 |
| Hostel Management | GHS 200 | GHS 2,500 |
| Transport Management | GHS 150 | GHS 1,500 |
| Inventory Management | GHS 100 | GHS 1,000 |
| HR & Payroll | GHS 250 | GHS 3,000 |
| CBT / Online Exams | GHS 300 | GHS 4,000 |
| E-Learning | GHS 300 | GHS 4,000 |
| Alumni Management | GHS 100 | GHS 1,000 |
| AI Assistant | GHS 400 | GHS 5,000 |
| Advanced Analytics | GHS 200 | GHS 2,500 |
| Mobile App (Student+Parent) | GHS 500 | GHS 8,000 |

**Plugin bundles (discount):**

| Bundle | Includes | Cloud/mo | School Edition |
|--------|---------|----------|----------------|
| Academic Bundle | Results + Attendance + CBT | GHS 450 | GHS 5,500 |
| Finance Bundle | Fees + Payroll + Accounting | GHS 550 | GHS 6,500 |
| Operations Bundle | Hostel + Transport + Inventory | GHS 400 | GHS 4,500 |
| Full School Bundle | All plugins | GHS 1,800 | GHS 20,000 |

---

## 5. Plugin Catalogue (V1 → V3 Roadmap)

### V1 Core (Ships with platform — not plugins)
- School Website CMS
- Admissions
- Student Information System (basic)
- Parent & Student Portal
- Announcements & Communication
- Admin Dashboard

### V1.5 Plugins (Build immediately after V1 launch)
These are the highest-demand plugins. Schools will ask for them first.

**Plugin: Results & Grading**
- Subject/course grade entry by teachers
- Grading system configuration (Ghana WAEC scale, custom)
- Automatic GPA/aggregate calculation
- Report card generation (PDF, school-branded)
- Result publishing (controlled release to portal)
- Terminal reports + cumulative reports
- Class position calculation
- Result SMS notification to parents

**Plugin: Attendance**
- Daily class attendance entry by teachers
- Attendance status: Present, Absent, Late, Excused
- Monthly attendance reports
- Low attendance alerts (email/SMS to parents)
- Attendance export (Excel)
- Academic year attendance summary

**Plugin: Online Fee Payments**
- Fee structure setup (tuition, boarding, uniform, etc.)
- Student fee assignment per term
- Payment integrations: MTN MoMo, Vodafone Cash, AirtelTigo, Paystack, Hubtel
- Payment receipts (PDF)
- Automated payment reminders (SMS/email)
- Outstanding fees report
- Payment history per student
- Accountant dashboard

### V2 Plugins (6–12 months post-launch)

**Plugin: Library Management**
- Book catalog (ISBN, author, category, copies)
- Borrowing & returns system
- Overdue tracking + fines
- Search catalog (student-facing)
- Barcode/QR support (future)
- Digital resource links
- Library reports

**Plugin: Hostel Management**
- Hostel/dormitory setup (blocks, rooms, beds)
- Student hostel allocation
- Bed assignment management
- Hostel fee tracking (links to Fee Payments plugin)
- Visitor log
- Hostel announcements (separate from school-wide)
- Hostel reports (occupancy, vacancies)

**Plugin: Transport Management**
- Bus/vehicle registration
- Route management
- Driver profiles
- Student transport assignment
- Pickup/dropoff scheduling
- Transport fee tracking (links to Fee Payments plugin)
- GPS integration (future)

**Plugin: Inventory Management**
- Asset register (furniture, equipment, electronics)
- Consumables tracking (stationery, lab supplies)
- Purchase records
- Stock alerts (low stock)
- Inventory reports
- Barcode support (future)

**Plugin: HR & Payroll**
- Staff records (beyond basic user profiles)
- Salary structures (grades, allowances, deductions)
- Monthly payroll processing
- Payslip generation (PDF)
- Leave management (types, application, approval)
- Staff attendance (separate from student attendance)
- SSNIT / tax deduction support
- Payroll reports

**Plugin: Alumni Management**
- Alumni profiles (graduated students auto-tagged)
- Alumni directory
- Alumni communication (email broadcasts)
- Donation/fundraising campaigns
- Events for alumni
- Alumni portal (separate login)

**Plugin: Advanced Analytics**
- Academic performance trends (class, subject, term)
- Attendance trend analysis
- Admissions funnel analytics
- Financial health dashboard
- Custom report builder
- Data export (Excel, PDF, CSV)
- Year-on-year comparisons

### V3 Plugins (12–24 months)

**Plugin: CBT / Online Exams**
- Question bank (MCQ, True/False, Short Answer)
- Exam builder (draw from question bank)
- Timed exams
- Auto-grading (MCQ)
- Randomized questions per student
- Anti-cheating: tab-switch detection, fullscreen enforcement
- Results release control
- Practice tests (student self-study)
- Exam analytics

**Plugin: E-Learning**
- Course creation (lessons, topics, resources)
- Video lessons (upload or YouTube/Vimeo embed)
- Assignment uploads + submissions
- Discussion forums per course
- Student progress tracking
- Certificate generation on completion
- Live class integration (Zoom/Google Meet)
- Learning analytics

**Plugin: AI Assistant**
- School chatbot (parent/student-facing, answers common questions)
- AI-generated report card comments (teacher saves time)
- AI admissions assistant (helps parents fill applications)
- AI-powered search across school content
- Predictive performance alerts (flags at-risk students early)
- AI-generated announcement drafts
- Powered by: Anthropic Claude API (or OpenAI)

**Plugin: Mobile App (Student + Parent)**
- React Native app (iOS + Android)
- Student: results, attendance, notifications, timetable
- Parent: child monitoring, fee payments, messaging, notifications
- Push notifications
- Offline mode for core data
- Branded per school (custom app name + icon for premium)
- Links to all installed plugins (results, fees, etc.)

---

## 6. License Key System (Self-Hosted Edition)

### Architecture

```
[School's Server]                         [Temsee License Server]
      |                                           |
      | Boot → VerifyLicense middleware            |
      | → POST /api/license/verify                |
      |   { key, domain, fingerprint }  ─────────>|
      |                                           | Validate key
      |                                           | Check domain
      |                                           | Check expiry
      |<── { valid: true, plan, expires_at } ─────|
      |                                           |
      | Cache result 24 hours                     |
      | If unreachable → 7-day grace              |
      |                                           |
      | Plugin boot → VerifyPluginLicense         |
      | → POST /api/plugin-license/verify         |
      |   { plugin_key, plugin_slug, domain } ───>|
      |<── { valid: true, plugin, expires_at } ───|
```

### License Server Database

```sql
-- Main system licenses
licenses (
  id, license_key, school_name, authorized_domain,
  plan, edition, status,
  issued_at, support_expires_at, max_students,
  fingerprint_hash, last_verified_at, created_at
)

-- Plugin licenses (per plugin per school)
plugin_licenses (
  id, plugin_slug, school_license_id,
  license_key, status,
  issued_at, expires_at, created_at
)

-- Verification logs
license_verifications (
  id, license_id, domain, ip_address,
  fingerprint, response, verified_at
)

plugin_license_verifications (
  id, plugin_license_id, plugin_slug,
  domain, ip_address, response, verified_at
)
```

### License Middleware

```php
// app/Http/Middleware/VerifyLicense.php
class VerifyLicense
{
    public function handle($request, Closure $next)
    {
        if (config('temseeedu.edition') === 'cloud') {
            return $next($request);
        }

        $status = Cache::remember('license_status', now()->addHours(24), function () {
            return $this->checkLicense();
        });

        if ($status === 'valid') return $next($request);
        if ($status === 'grace') {
            session()->flash('license_warning', 'License verification failed. Grace period active.');
            return $next($request);
        }

        return response()->view('license.expired', [], 402);
    }

    private function checkLicense(): string
    {
        try {
            $response = Http::timeout(10)->post('https://license.temseeedu.com/api/verify', [
                'key'         => config('temseeedu.license_key'),
                'domain'      => request()->getHost(),
                'fingerprint' => $this->getServerFingerprint(),
            ]);

            if ($response->successful() && $response->json('valid')) {
                Cache::put('license_grace_counter', 0);
                return 'valid';
            }

            return $this->handleFailure();
        } catch (\Exception $e) {
            return $this->handleFailure();
        }
    }

    private function handleFailure(): string
    {
        $graceDays = Cache::get('license_grace_counter', 0);
        if ($graceDays < 7) {
            Cache::increment('license_grace_counter');
            return 'grace';
        }
        return 'invalid';
    }

    private function getServerFingerprint(): string
    {
        return hash('sha256', gethostname() . config('database.connections.mysql.database'));
    }
}
```

### Plugin License Manager

```php
// app/Services/PluginLicenseManager.php
class PluginLicenseManager
{
    public static function verify(string $pluginSlug): self
    {
        $instance = new self($pluginSlug);
        return $instance;
    }

    public function isValid(): bool
    {
        // Cloud edition: check plugin is active for school's plan
        if (config('temseeedu.edition') === 'cloud') {
            return $this->checkCloudPlugin();
        }

        // School Edition: verify plugin license key with license server
        return Cache::remember("plugin_license_{$this->slug}", now()->addHours(24), function () {
            return $this->verifyWithServer();
        });
    }

    private function verifyWithServer(): bool
    {
        $key = config("temseeedu.plugins.{$this->slug}.license_key");

        if (!$key) return false;

        try {
            $response = Http::timeout(10)->post('https://license.temseeedu.com/api/plugin-license/verify', [
                'plugin_key'  => $key,
                'plugin_slug' => $this->slug,
                'domain'      => request()->getHost(),
            ]);

            return $response->successful() && $response->json('valid');
        } catch (\Exception $e) {
            // Grace: if system license is in grace, extend plugin grace too
            return Cache::get("plugin_grace_{$this->slug}", false);
        }
    }

    private function checkCloudPlugin(): bool
    {
        $school = app('currentSchool');
        return $school->hasPlugin($this->slug);
    }
}
```

### Plugin Config (School Edition .env)

```env
TEMSEEEDU_EDITION=school_edition
TEMSEEEDU_LICENSE_KEY=TSEDU-XXXX-XXXX-XXXX-XXXX

# Plugin license keys (added as each plugin is purchased)
TEMSEEEDU_PLUGIN_RESULTS_KEY=TSPLUGIN-RESULTS-XXXX-XXXX
TEMSEEEDU_PLUGIN_ATTENDANCE_KEY=TSPLUGIN-ATTEND-XXXX-XXXX
TEMSEEEDU_PLUGIN_FEES_KEY=TSPLUGIN-FEES-XXXX-XXXX
TEMSEEEDU_PLUGIN_HOSTEL_KEY=TSPLUGIN-HOSTEL-XXXX-XXXX
TEMSEEEDU_PLUGIN_LIBRARY_KEY=TSPLUGIN-LIB-XXXX-XXXX
TEMSEEEDU_PLUGIN_CBT_KEY=TSPLUGIN-CBT-XXXX-XXXX
```

### License Event Behavior

| Event | System Behavior |
|-------|----------------|
| License valid | Full access, cache 24 hours |
| License server unreachable | Grace period (7 days), warning banner |
| Grace period expired | Read-only mode, admin actions locked |
| License suspended | Redirect to payment/contact page |
| License revoked | Hard lock, contact Temsee message |
| Plugin license missing | Plugin hidden from UI, data preserved |
| Plugin license expired | Plugin locked, data preserved, renewal prompt |
| Support contract expired | App works, update notifications disabled |

---

## 7. Target Users for V1

| User | Description |
|------|-------------|
| **School Admin** | Manages entire school setup, settings, users, plugins |
| **Admissions Officer** | Reviews applications, manages applicants |
| **Teacher** | Views class students, posts announcements, uses academic plugins |
| **Accountant** | Manages fees and financial reports (Fee Payments plugin) |
| **Student** | Views personal info, uses portal + plugin features |
| **Parent/Guardian** | Monitors child, receives notifications, pays fees |
| **Super Admin** | Temsee — manages all Cloud schools, plugin activations |
| **License Admin** | Temsee staff — manages self-hosted licenses and plugin keys |

---

## 8. V1 Core Modules

### Module 1 — School Website CMS

**Features:**
- Homepage builder with pre-built sections (hero, about, programs, gallery, contact)
- News & announcements management
- Events calendar
- Gallery (photos + optional video embed)
- Leadership/staff profiles
- School prospectus upload
- Admissions landing page (connected to Module 2)
- Contact form with email notification
- Custom pages (About, Academics, Student Life)
- SEO fields (meta title, description, OG image per page)
- Mobile-first responsive design

**Cloud edition:** `schoolname.temseeedu.com`
**School Edition:** school's own domain e.g. `ameziongirls.edu.gh`

**User Stories:**

| As a... | I want to... | So that... |
|---------|-------------|------------|
| School Admin | Update homepage hero text and image | The website reflects current branding |
| School Admin | Publish a news article | Parents and visitors stay informed |
| Parent (visitor) | Browse school info on mobile | I can make informed admissions decisions |
| Admissions Officer | Direct parents to the apply page | Applications come through the system |

---

### Module 2 — Admissions

**Features:**
- Public online application form
- Document upload (birth certificate, BECE results, passport photo)
- Application status tracking (Pending → Under Review → Accepted/Rejected)
- Applicant tracker (public, login via reference number + DOB)
- Admissions officer dashboard
- Admission letter generation (PDF)
- Email notifications at each status change
- SMS notification via Arkesel (optional)
- Entrance exam scheduling (date + venue)
- Prospectus download
- Application reference number generation

**User Stories:**

| As a... | I want to... | So that... |
|---------|-------------|------------|
| Parent | Apply online for my child | I don't have to travel to apply |
| Applicant | Track my application status | I know what's happening |
| Admissions Officer | Review all applications in one place | I manage them efficiently |
| Admissions Officer | Accept or reject with one click | The process is faster |
| Applicant | Download my admission letter | I have official proof of admission |

---

### Module 3 — Student Information System (Basic)

**Features:**
- Student profile (name, ID, class, house, guardian info, photo)
- Student ID number generation (auto on admission approval)
- Class/section assignment
- Academic year tracking
- Student document storage
- Student status (active, graduated, withdrawn, suspended)
- Student ID card generation (PDF)
- Basic search and filter

**What's NOT in V1 core (plugin territory):**
- Grades / results → Results & Grading plugin
- Attendance → Attendance plugin
- Discipline records → V2
- Fee records → Fee Payments plugin

**User Stories:**

| As a... | I want to... | So that... |
|---------|-------------|------------|
| Admin | View all students centrally | I have one source of truth |
| Admin | Generate a student ID card | Students have official identification |
| Teacher | See students in my class | I can manage my class |
| Student | View my profile and documents | I have access to my school records |

---

### Module 4 — Parent & Student Portal

**Student sees:**
- Personal profile
- Class and teacher info
- School announcements
- Downloadable documents
- School events calendar
- Fee status display (with Fee Payments plugin)
- Results (with Results plugin)
- Attendance record (with Attendance plugin)

**Parent sees:**
- Child's profile snapshot
- School announcements
- Fee payment status + payment button (with Fee Payments plugin)
- School events
- Contact school
- Notification history

**User Stories:**

| As a... | I want to... | So that... |
|---------|-------------|------------|
| Student | Log in and see my school info | I don't need to ask admin everything |
| Parent | See my child's current status | I feel connected to the school |
| Parent | Receive notifications | I don't miss important updates |
| Parent | Contact the school easily | Communication is smooth |

---

### Module 5 — Announcements & Communication

**Features:**
- School-wide announcements
- Target by audience: all, parents, students, teachers, specific class
- Announcement types: General, Urgent, Event, Academic
- Push notifications (in-app)
- Email broadcast (SendGrid/Mailgun)
- SMS broadcast (Arkesel — toggleable)
- Announcement scheduling
- Announcement archive
- Mark as read tracking

**User Stories:**

| As a... | I want to... | So that... |
|---------|-------------|------------|
| Admin | Send an urgent school notice | Everyone is informed immediately |
| Admin | Schedule a reminder for events | I don't have to post manually |
| Parent | Receive notifications on my phone | I never miss important news |
| Teacher | Post class-specific notices | My students get targeted updates |

---

### Module 6 — Admin Dashboard

**Dashboard widgets:**
- Total students / active / new this term
- Pending applications (quick-access link)
- Recent announcements
- Upcoming events
- Quick actions: New Announcement, Review Applications, Add Student
- Plugin status overview (which are active)
- License / subscription status

**Settings panel:**
- School name, logo, colors, tagline
- Academic year + term setup
- Email configuration (SMTP)
- SMS API key (Arkesel)
- User management (add staff, assign roles)
- Plugin marketplace link (Cloud) / Plugin installer (School Edition)
- Subscription status (Cloud) / License info (School Edition)

---

### Module 7 — Plugin Engine (Core)

This module ships with V1 but powers all future plugins.

**What it provides:**
- Plugin registry (list of all available plugins)
- Plugin enable/disable (Cloud: instant, School Edition: via zip upload)
- Plugin marketplace UI in admin panel
- Plugin license validation layer
- Plugin settings isolation (each plugin has its own settings namespace)
- Plugin event hooks (plugins subscribe to core events)
- Plugin sidebar injection (Filament panel extension)
- Plugin migration runner
- Plugin update checker
- Plugin dependency resolver (e.g. Fee Payments requires core SIS)

**Core events plugins can hook into:**
```php
// Events fired by the core that plugins can listen to:
StudentCreated::class        // → Attendance plugin creates attendance record
StudentPromoted::class       // → Results plugin archives previous term data
ApplicationApproved::class   // → Fee Payments plugin creates initial fee record
AnnouncementPublished::class // → Mobile App plugin sends push notification
TermStarted::class           // → All academic plugins initialize for new term
```

---

## 9. Architecture

### Cloud Edition — Multi-Tenant

```
temseeedu.com                  → Marketing/landing page
ameziongirls.temseeedu.com     → AME Zion Girls school instance
wesleygirls.temseeedu.com      → Wesley Girls school instance
```

- Each school's data scoped by `school_id`
- Schools cannot see each other's data
- Super Admin (Temsee) can view all schools
- Plugins activated per school, billed per school
- Wildcard SSL: `*.temseeedu.com`

### School Edition — Single Tenant

```
ameziongirls.edu.gh            → School's own domain
```

- One school per installation
- No `school_id` scoping needed
- School manages their own hosting
- Plugins installed as separate encoded zip files
- Each plugin has its own license key

---

## 10. Tech Stack

### Backend
| Layer | Choice | Reason |
|-------|--------|--------|
| Framework | Laravel 11 | Mature, fast to build |
| Plugin Engine | nWidart/laravel-modules | Industry standard for Laravel modular architecture |
| Auth | Laravel Breeze + Spatie Permission | Simple, role-based |
| Admin UI | Filament 3 | Beautiful, supports plugin panel extensions |
| File Storage | Spatie Media Library | Clean file management |
| PDF Generation | DomPDF | Admission letters, ID cards, report cards |
| Email | Laravel Mail + Mailgun/SendGrid | Reliable delivery |
| SMS | Arkesel (Ghana) | Local SMS gateway |
| Queue | Laravel Queue + Redis | Notifications, emails, heavy jobs |
| Search | Laravel Scout | Student/application search |
| Exports | Laravel Excel (Maatwebsite) | Lists, reports |
| Code Protection | SourceGuardian | School Edition encoding |
| HTTP Client | Laravel HTTP (Guzzle) | License server communication |

### Frontend
| Layer | Choice | Reason |
|-------|--------|--------|
| School Public Website | Blade + TailwindCSS + Alpine.js | Fast, SEO-friendly |
| Admin Dashboard | Filament 3 (Livewire) | Supports plugin panel injection |
| Portals (Student/Parent) | Blade + Livewire + TailwindCSS | Real-time feel |
| Animations | GSAP + CSS | Smooth, modern feel |

### Infrastructure — Cloud Edition
| Layer | Choice |
|-------|--------|
| App Hosting | VPS (Hetzner / DigitalOcean) |
| License Server | Separate VPS, Laravel API only |
| Database | MySQL 8 |
| Cache | Redis |
| Storage | VPS local + S3 later |
| DNS | Wildcard `*.temseeedu.com` |
| SSL | Let's Encrypt wildcard |
| CI/CD | GitHub Actions |

### Infrastructure — School Edition
| Layer | Notes |
|-------|-------|
| Hosting | School's cPanel / VPS / server |
| Database | MySQL (school managed) |
| PHP Version | 8.3+ required |
| SourceGuardian Loader | Must be installed on server |

---

## 11. Database Schema

### Cloud Edition (multi-tenant)

```sql
-- Platform level
schools (
  id, name, slug, domain, logo, colors_json,
  status, subscription_plan, subscription_status,
  subscription_ends_at, grace_period_ends_at, created_at
)

subscriptions (
  id, school_id, plan, status,
  starts_at, ends_at, grace_period_ends_at, created_at
)

school_plugins (
  id, school_id, plugin_slug, status,
  activated_at, billing_type, price, next_billing_at
)

super_admins (id, name, email, password)

-- School level (scoped by school_id)
users (id, school_id, name, email, password, role, status)
students (id, school_id, user_id, student_id_no, class_id, guardian_id, status, photo)
guardians (id, school_id, name, email, phone, relationship)
classes (id, school_id, name, level, academic_year_id)
academic_years (id, school_id, name, start_date, end_date, is_current)
terms (id, school_id, academic_year_id, name, start_date, end_date, is_current)

-- Admissions
applications (
  id, school_id, applicant_name, dob, program,
  status, reference_no, guardian_name,
  guardian_phone, guardian_email, documents_json
)

-- CMS
pages (id, school_id, slug, title, content_json, is_published, meta_json)
news (id, school_id, title, body, image, published_at, author_id)
events (id, school_id, title, description, date, location, image)
gallery_items (id, school_id, type, url, caption, category)

-- Communication
announcements (
  id, school_id, title, body, type,
  audience, scheduled_at, published_at, author_id
)
notifications (id, user_id, type, title, body, read_at, data_json)
```

### Plugin Tables (examples — created by each plugin's migration)

```sql
-- Results & Grading plugin
grades (id, school_id, student_id, subject_id, term_id, score, grade, remarks)
report_cards (id, school_id, student_id, term_id, pdf_path, published_at)

-- Attendance plugin
attendance_records (id, school_id, student_id, class_id, date, status, recorded_by)

-- Fee Payments plugin
fee_structures (id, school_id, term_id, name, amount, category)
student_fees (id, school_id, student_id, fee_structure_id, status, due_date)
payments (id, school_id, student_id, amount, method, reference, paid_at)

-- Hostel plugin
hostels (id, school_id, name, capacity)
hostel_rooms (id, hostel_id, room_number, bed_count)
hostel_allocations (id, school_id, student_id, room_id, bed_number, term_id)

-- Library plugin
books (id, school_id, title, author, isbn, copies_total, copies_available)
book_borrows (id, school_id, book_id, student_id, borrowed_at, due_date, returned_at)
```

---

## 12. Key Pages & Routes

### Public School Website
```
/                        → Homepage
/about                   → About school
/academics               → Academic programs
/admissions              → Admissions info + Apply CTA
/admissions/apply        → Application form
/admissions/track        → Application status tracker
/news                    → News listing
/news/{slug}             → Single news article
/events                  → Events
/gallery                 → Gallery
/contact                 → Contact form
```

### Student Portal
```
/portal/login            → Login
/portal/dashboard        → Student home
/portal/profile          → Personal info
/portal/documents        → Downloads
/portal/announcements    → School notices
/portal/events           → Calendar
/portal/results          → Results (Results plugin)
/portal/attendance       → Attendance (Attendance plugin)
/portal/fees             → Fee status + payment (Fee Payments plugin)
```

### Parent Portal
```
/parent/login            → Login
/parent/dashboard        → Parent home
/parent/child/{id}       → Child's profile
/parent/announcements    → School notices
/parent/fees             → Fee status + payment (Fee Payments plugin)
/parent/contact          → Message school
```

### Admin Panel (Filament)
```
/admin                   → Dashboard
/admin/students          → Student management
/admin/admissions        → Applications
/admin/announcements     → Communication
/admin/news              → CMS news
/admin/events            → CMS events
/admin/gallery           → Media
/admin/pages             → Page editor
/admin/users             → Staff/roles
/admin/settings          → School settings
/admin/license           → License info (School Edition)
/admin/plugins           → Plugin marketplace (Cloud)
/admin/plugins/installed → Manage installed plugins

-- Plugin-injected routes (examples):
/admin/results           → Results management (Results plugin)
/admin/attendance        → Attendance (Attendance plugin)
/admin/fees              → Fee management (Fee Payments plugin)
/admin/library           → Library (Library plugin)
/admin/hostel            → Hostel (Hostel plugin)
/admin/payroll           → Payroll (HR & Payroll plugin)
/admin/exams             → CBT Exams (CBT plugin)
```

### License Server (Temsee internal)
```
https://license.temseeedu.com/api/verify              → POST (system license check)
https://license.temseeedu.com/api/plugin-license/verify → POST (plugin license check)
https://license.temseeedu.com/admin                   → Temsee license dashboard
```

---

## 13. Build Phases

### Phase 0 — Foundation + License + Plugin Engine (Week 1–3)

**Core setup:**
- [ ] Laravel 11 project setup
- [ ] `config/temseeedu.php` (edition, license key, plugin keys)
- [ ] nWidart/laravel-modules installation and configuration
- [ ] Multi-tenant middleware (Cloud: subdomain routing / School Edition: single domain)
- [ ] Database schema migrations (core tables)
- [ ] Spatie Permission — define all roles
- [ ] Filament 3 installation and theme customization
- [ ] Auth system (Admin, Student, Parent separate guards)
- [ ] School settings panel
- [ ] Super Admin panel (Cloud — create/manage schools)

**License system (School Edition):**
- [ ] Build License Server as a separate Laravel app
- [ ] License server database + migrations (licenses + plugin_licenses)
- [ ] System license verification API (`POST /api/verify`)
- [ ] Plugin license verification API (`POST /api/plugin-license/verify`)
- [ ] `VerifyLicense` middleware (main app)
- [ ] `PluginLicenseManager` service class
- [ ] 24-hour cache + 7-day grace period logic
- [ ] License expired / suspended view
- [ ] License admin dashboard (Filament, Temsee only)
- [ ] Issue / suspend / revoke system licenses
- [ ] Issue / revoke plugin licenses
- [ ] Verification history log

**Subscription system (Cloud Edition):**
- [ ] `school_plugins` table + subscription tables
- [ ] `CheckSubscription` middleware
- [ ] Plugin activation/deactivation per school
- [ ] Email warnings before subscription expiry

**Plugin engine:**
- [ ] Plugin registry (list of all available plugins from config)
- [ ] Plugin enable/disable command (`php artisan plugin:enable hostel`)
- [ ] Plugin marketplace UI in Filament (Cloud)
- [ ] Plugin zip uploader + installer (School Edition)
- [ ] Plugin settings namespace isolation
- [ ] Core event definitions (StudentCreated, ApplicationApproved, etc.)
- [ ] Filament sidebar injection support for plugins
- [ ] Plugin migration runner on enable
- [ ] Plugin data preservation on disable (tables remain)
- [ ] `plugin:list` artisan command (shows installed + status)

---

### Phase 1 — Website CMS (Week 4–5)
- [ ] Public school homepage (Blade + Tailwind design)
- [ ] Homepage sections: hero, about, programs, gallery, contact
- [ ] CMS controls in Filament
- [ ] News management
- [ ] Events management
- [ ] Gallery management
- [ ] Contact form
- [ ] SEO fields per page
- [ ] Custom domain support (School Edition)
- [ ] Mobile responsiveness audit

### Phase 2 — Admissions (Week 6–7)
- [ ] Public application form
- [ ] Document upload
- [ ] Reference number generation
- [ ] Applicant status tracker
- [ ] Admissions officer dashboard
- [ ] Status workflow
- [ ] Email notifications
- [ ] Admission letter PDF
- [ ] Prospectus download

### Phase 3 — Student SIS (Week 8)
- [ ] Student profile (auto-created on approval)
- [ ] Manual student creation
- [ ] Class assignment
- [ ] Student ID generation
- [ ] Student ID card PDF
- [ ] Document storage
- [ ] Student list with search + filter + export
- [ ] Academic year + term management

### Phase 4 — Portals (Week 9–10)
- [ ] Student portal
- [ ] Parent portal
- [ ] Portal mobile design (priority)
- [ ] In-app notification bell
- [ ] Plugin-aware portal sections (show plugin content when active)

### Phase 5 — Communication (Week 10–11)
- [ ] Announcements system
- [ ] Email broadcast
- [ ] In-app notifications
- [ ] SMS broadcast (Arkesel)
- [ ] Announcement archive

### Phase 6 — First Plugins (Week 12–14)

Build the two most-requested plugins immediately after core:

**Results & Grading plugin:**
- [ ] Subject setup per class
- [ ] Grade entry by teacher (Filament form)
- [ ] Grading scale configuration (Ghana WAEC + custom)
- [ ] GPA / aggregate calculation
- [ ] Report card PDF generation
- [ ] Result publishing control
- [ ] Results visible in student portal
- [ ] SMS result notification to parents

**Attendance plugin:**
- [ ] Daily attendance entry by teacher
- [ ] Attendance status options
- [ ] Monthly report
- [ ] Low attendance alerts
- [ ] Attendance export
- [ ] Attendance visible in student portal

### Phase 7 — Polish & Launch (Week 15–16)
- [ ] SourceGuardian encoding pipeline (core + per plugin)
- [ ] School Edition installer
- [ ] Onboarding wizard
- [ ] Demo instance: `demo.temseeedu.com`
- [ ] Performance audit
- [ ] Security audit
- [ ] QA: mobile + desktop, both editions, all installed plugins
- [ ] `temseeedu.com` marketing page
- [ ] Pricing page (core plans + plugin pricing clearly shown)
- [ ] School admin documentation

---

## 14. SourceGuardian Encoding Pipeline

### Core encoding (before School Edition delivery)

```bash
#!/bin/bash
# scripts/build-school-edition.sh

VERSION=$1  # e.g. 1.0.0

# Clean build directory
rm -rf ./dist/school-edition/
mkdir -p ./dist/school-edition/

# Checkout production branch
git checkout main && git pull

# Install production dependencies
composer install --no-dev --optimize-autoloader
npm run build

# Remove cloud-only code
rm -rf app/Http/Middleware/ResolveTenant.php
rm -rf app/Models/Subscription.php

# Encode with SourceGuardian
sgenc --php 8.3 \
      --exclude storage/ \
      --exclude public/assets/ \
      --exclude public/build/ \
      --exclude resources/ \
      --exclude tests/ \
      --output ./dist/school-edition/ \
      ./

# Set edition in env example
echo "TEMSEEEDU_EDITION=school_edition" >> ./dist/school-edition/.env.example
echo "TEMSEEEDU_LICENSE_KEY=" >> ./dist/school-edition/.env.example

# Zip core
zip -r "TemseeEdu-Core-v${VERSION}.zip" ./dist/school-edition/

echo "Core build complete: TemseeEdu-Core-v${VERSION}.zip"
```

### Plugin encoding (per plugin before delivery)

```bash
#!/bin/bash
# scripts/build-plugin.sh

PLUGIN=$1   # e.g. hostel
VERSION=$2  # e.g. 1.0.0

rm -rf ./dist/plugins/${PLUGIN}/
mkdir -p ./dist/plugins/${PLUGIN}/

sgenc --php 8.3 \
      --exclude app-modules/${PLUGIN}/Resources/views/ \
      --output ./dist/plugins/${PLUGIN}/ \
      ./app-modules/${PLUGIN}/

echo "TEMSEEEDU_PLUGIN_${PLUGIN^^}_KEY=" >> ./dist/plugins/${PLUGIN}/.env.append

zip -r "TemseeEdu-Plugin-${PLUGIN}-v${VERSION}.zip" ./dist/plugins/${PLUGIN}/

echo "Plugin build complete: TemseeEdu-Plugin-${PLUGIN}-v${VERSION}.zip"
```

---

## 15. Choosing the Right Edition (Sales Guide)

| Question | Cloud | School Edition |
|----------|-------|----------------|
| Do you have your own server? | No | Yes |
| Do you have an IT person on staff? | No | Preferred |
| Comfortable with monthly payments? | Yes | No |
| Need data on your own server? | No | Yes |
| Government / public school? | Unlikely | Likely |
| Want automatic updates? | Yes | Support contract |
| Budget: monthly or lump sum? | Monthly | Lump sum |

**Default for most private schools:** Cloud Edition.
**Default for government SHS, universities:** School Edition.

---

## 16. Plugin Revenue Projections

**Scenario: 20 Cloud schools on Growth plan**

| Revenue Source | Monthly |
|---------------|---------|
| 20 × GHS 800 base plan | GHS 16,000 |
| 10 schools × Results plugin GHS 150 | GHS 1,500 |
| 10 schools × Attendance plugin GHS 100 | GHS 1,000 |
| 5 schools × Fee Payments plugin GHS 200 | GHS 1,000 |
| 3 schools × Hostel plugin GHS 200 | GHS 600 |
| **Total MRR** | **GHS 20,100** |

**Scenario: 5 School Edition clients**

| Revenue Source | One-Time |
|---------------|---------|
| 5 × GHS 8,000 base license | GHS 40,000 |
| 5 × GHS 1,500 setup fee | GHS 7,500 |
| 3 × Results plugin GHS 1,500 | GHS 4,500 |
| 2 × Hostel plugin GHS 2,500 | GHS 5,000 |
| 5 × GHS 1,500 annual support | GHS 7,500/yr |
| **Year 1 total** | **~GHS 64,500** |

---

## 17. What's NOT in V1

Be disciplined. These come later via plugins:

| Feature | Delivery Method | Target |
|---------|----------------|--------|
| Results / Grading | Plugin | Phase 6 |
| Attendance | Plugin | Phase 6 |
| Fee Payments (online) | Plugin | V1.5 |
| Library | Plugin | V2 |
| Hostel | Plugin | V2 |
| Transport | Plugin | V2 |
| Inventory | Plugin | V2 |
| HR & Payroll | Plugin | V2 |
| CBT / Exams | Plugin | V3 |
| E-Learning | Plugin | V3 |
| AI Assistant | Plugin | V3 |
| Mobile App | Plugin | V3 |
| Alumni | Plugin | V2 |
| Advanced Analytics | Plugin | V2 |

---

## 18. First Client Strategy

Don't wait for the full build. Move in parallel.

**Month 1–2:** Phase 0 + Phase 1 (Foundation + CMS)
→ Pitch AME Zion Girls SHS with live demo on their subdomain or domain.
→ Let them choose Cloud or School Edition. Charge setup fee + first payment.

**Month 2–3:** Phase 2 (Admissions)
→ Upgrade existing client. Pitch 2 more schools using AME Zion as case study.

**Month 3–4:** Phases 3–5 (SIS + Portals + Communication)
→ Full V1 core complete.

**Month 4–5:** Phase 6 (Results + Attendance plugins)
→ Upsell existing clients immediately. New clients get the full package.

**The strategy:** Revenue while building. Plugins create upsell opportunities
at every conversation with existing clients.

---

## 19. Success Metrics for V1

| Metric | Target |
|--------|--------|
| Schools onboarded | 3–5 |
| Monthly Recurring Revenue (Cloud) | GHS 3,000+ |
| School Edition licenses sold | 2+ |
| Plugins sold / activated | 5+ |
| Uptime (Cloud + License Server) | 99%+ |
| Mobile Lighthouse Score | 85+ |
| Application form completion rate | 70%+ |
| Admin onboarding time | < 30 minutes |
| Plugin install time (School Edition) | < 10 minutes |

---

*TemseeEdu V1 PRD v3.0 — Internal Build Document*
*Temsee © 2025*