# SOQ TMS Implementation Documentation

## 1. Purpose

This document sits **on top of the PRD** and translates product intent into implementation direction.

It answers:

- what we are building first
- how the platform is structured
- what belongs in the base system
- what becomes a module
- how delivery is phased
- how changes are handled in future
- which technical decisions are locked now

This document should be read together with:

- `SOQ_Training_Management_System_Proposal.pdf`
- `SOQ_TMS_PRD.md`
- `SOQ_TMS_PRD_v1.1_clean.md`
- `SOQ_TMS_PRD_v1.1_redline.md`

## 2. Confirmed implementation direction

The implementation model is:

- **multi-tenant SaaS platform**
- **multi-tenant-ready from day one, without overbuilding full tenant self-service admin in phase 1**
- **modular monolith for initial delivery**
- **base platform + core modules + optional modules**
- **Laravel + PostgreSQL + React**
- **Redis-backed queue/event processing**
- **SWDA Hub as the first likely future extraction candidate**

We are **not** treating this as a one-off bespoke system and we are **not** starting with microservices.

## 2.1 Proposed directory structure (summary)

Full tree: **CRD Section 04 · [Proposed Directory Structure](/docs/proposed-directory-structure)** in the documentation site.

```
soq-tms/
├── apps/           # public-web, student-portal, admin-workspace, trainer-portal
├── packages/       # ui, api-client, auth, forms
├── services/api/   # Laravel modular monolith
│   ├── modules/    # Identity, Catalogue, Admissions, Enrolment, …
│   └── integrations/  # SwdaHub, Xero
├── infrastructure/ # docker, terraform, ci
└── docs/           # PRD, CRD, ADRs
```

## 3. Delivery principles

1. Build the base platform once.
2. Keep client variation in configuration, workflow rules, templates and module enablement.
3. Add business capability as modules, not scattered custom code.
4. Protect the main academic/funding workflow from optional-module sprawl.
5. Keep one source of truth for identity, enrolment, attendance, assessment and orders.
6. Use events and queues for cross-module and external-system flows.
7. Only allow code forks by explicit exception.

## 4. Platform structure

### 4.1 Base platform

The base platform must exist before optional modules are safe to add.

Included:

- tenant / organisation model
- user identity and authentication
- role and permission framework
- workflow / approvals engine
- audit trail and activity logging
- document management shell
- notification framework
- operational dashboard shell
- core reporting and export shell
- integration framework
- environment and deployment standards

### 4.2 Core modules for SOQ Phase 1

These are the modules that protect SOQ's main operating objective:

- catalogue and course runs
- admissions
- identity and applicant journeys
- enrolment and Student 360
- attendance
- assessment and certification
- core finance order flow
- WSQ registration and required funding evidence flow

### 4.3 Optional / installable modules

These should not destabilise the core launch path:

- CRM lead and opportunity management
- sales commission
- advanced learning engagement features
- trainer fee payout workflow
- Xero integration
- SWDA/WSQ Integration Hub extensions beyond minimum required scope
- advanced analytics and dashboards

## 5. Application map

### 5.1 User-facing applications

- **Student Portal**
  - catalogue
  - enquiry
  - application
  - registration
  - learner self-service

- **Admin Workspace**
  - course and fee setup
  - admissions and approvals
  - enrolment and Student 360
  - attendance exception management
  - assessment release
  - finance operations
  - reporting and governance

- **Trainer Portal**
  - schedule
  - attendance capture
  - assessment workflow
  - trainer availability
  - earnings visibility

### 5.2 Shared services

- identity service
- workflow / approvals service
- audit and governance service
- notification service
- document service
- reporting shell
- integration service

## 6. Module map

### 6.1 Core modules

| Module | Main responsibility | Main owned records |
|---|---|---|
| Identity | person lifecycle and access | person, identity, consent, auth linkage |
| Catalogue | programme, course, module and pricing setup | programme, course, module, pricing |
| Admissions | applications, screening, offers | application, decision, offer, reviewer task |
| Enrolment | cohort/run participation and status | enrolment, class assignment, status, hold |
| Attendance | session attendance and verification | session attendance, evidence, correction |
| Assessment | submissions, marking, moderation, release | assessment, submission, result, appeal |
| Certification | completion and certificate issuance | completion, certificate, transcript |
| Finance Core | order and payment control | order, invoice request, refund request |

### 6.2 Optional modules

| Module | Main responsibility | Dependency notes |
|---|---|---|
| CRM | enquiries, leads, opportunities | depends on Identity, Catalogue |
| Commission | agent commission logic | depends on CRM and Finance Core |
| Trainer Fees | payable trainer earnings and claims | depends on Attendance, Trainer Portal, Finance Core |
| Xero | accounting sync | depends on Finance Core |
| SWDA Hub | government integration layer | depends on Identity, Enrolment, Attendance, Assessment, Finance Core |
| Learning Extras | engagement tools, discussions, advanced content controls | depends on Student Portal |
| Analytics | advanced dashboards and exports | consumes from all modules |

## 7. Technical architecture

### 7.1 Backend

- Laravel is the primary backend framework.
- Modules live inside one modular monolith codebase.
- Modules expose application services and events, not uncontrolled direct table access.
- Queue-backed jobs handle integration calls, retries and asynchronous work.

### 7.2 Frontend

- React is used for Student Portal, Admin Workspace and Trainer Portal.
- Shared design system and auth/session model across all portals.
- Module features appear as route groups / UI slices, not separate frontend codebases unless justified later.

### 7.3 Database

- PostgreSQL is the transactional system of record.
- Each module owns its main tables and write paths.
- Shared identifiers are consistent across modules.
- Audit-sensitive records use immutable history where needed.

### 7.4 Async and integration pattern

- Redis for queueing and short-lived cache.
- Outbox pattern for external posting.
- Idempotent integration handlers.
- Retry with back-off.
- Dead-letter / exception handling for failed integration jobs.

## 8. Data ownership and boundaries

Rules:

1. Each module owns its primary records.
2. Cross-module writes happen through application services, orchestration or events.
3. Reporting may read across modules, but operational writes do not bypass ownership.
4. Integrations never become a side door into module data.

Important ownership examples:

- Identity owns person matching and merge rules.
- Attendance owns attendance evidence and correction history.
- Assessment owns result release.
- Finance Core owns order state changes that affect money.
- SWDA Hub owns submission state to government systems.
- Xero module owns external accounting sync state.

## 9. Environment and deployment model

Environments:

- development
- staging
- production

Shared deployment rules:

- AWS Singapore region
- managed PostgreSQL
- Redis for queue/cache
- object storage for files and certificates
- secrets in managed secret storage
- centralised logs, metrics and alerting

## 10. Security, privacy and audit

Must-have implementation controls:

- MFA for privileged users
- role-based access with data-level restrictions
- approval checkpoints for money, results and funding submissions
- immutable audit trail for critical actions
- retention matrix by record type
- legal hold / audit hold support
- field-level anonymisation after lawful retention expiry
- security review before UAT
- penetration testing or equivalent assurance before go-live

## 11. Attendance and funding evidence model

This is one of the highest-risk implementation areas.

Implementation rules:

- classroom and Zoom attendance cannot use identical proof logic
- funded attendance requires anti-proxy controls
- attendance windows and grace rules must be configurable
- disputes require evidence and approval
- retention periods must respect funding/audit obligations
- SWDA submission status must remain visible and recoverable

## 12. Finance and Xero model

Implementation rules:

- TMS owns course pricing, subsidy application, exemptions and order logic
- Xero remains the accounting system for posted accounting transactions
- posting policy must define what auto-posts and what waits for approval
- every posting must be idempotent and replay-safe
- reconciliation state must be visible to operations

## 13. Change management model

Future changes are handled in this order:

1. configuration change
2. workflow/template change
3. enable an existing module
4. extend a module
5. create a new module
6. approve a code fork only as an exception

This prevents normal business change from turning into platform fragmentation.

## 14. Delivery phases

### Phase 1

Base platform + core SOQ operational modules:

- identity
- catalogue
- admissions
- enrolment
- attendance
- assessment
- certification
- core finance

### Phase 2

Optional modules as justified:

- CRM
- commission
- trainer fees
- Xero
- broader SWDA automation
- advanced learning engagement
- advanced analytics

## 15. Go-live readiness checklist

Before go-live, confirm:

- identity and roles work
- admissions and enrolment flow works
- attendance capture, approval and correction work
- assessment release works
- funding submission path is proven
- posting approval matrix is approved
- privacy and retention policy is approved
- critical defects are closed or risk-accepted

## 16. Open implementation decisions to lock next

- exact tenant model for future clients
- final module packaging and enablement rules
- identity merge decision policy
- final SWDA API scope
- final Xero posting matrix
- payment gateway choice
- reporting architecture for future analytics scale
- whether any module needs early extraction from the monolith

## 17. Recommended next documents

After this document, the next implementation artefacts should be:

1. technical architecture diagram
2. module boundary specification
3. database/domain model specification
4. integration specification
5. role/permission matrix
6. workflow/approval matrix
7. delivery backlog by phase and module

## 18. Cross-check against ERP reference features

Based on the ERP reference shared in the thread, the implementation should clearly show what is:

- already aligned to SOQ TMS
- relevant but optional
- not part of the current product objective

### 18.1 Already aligned / should be explicit

| ERP reference item | SOQ implementation status |
|---|---|
| User authentication and roles | Included in base platform |
| Dashboard overview | Included in Admin Workspace as core operational dashboards |
| Reports and analytics | Core reports/exports included; advanced analytics remains optional |
| Role-based access control | Included in base platform |
| Workflow automation | Included through workflow / approvals engine |
| Real-time notifications | Included through notification framework |
| Responsive design | Included; Trainer Portal is mobile-first |
| Multi-company support | Covered through multi-tenant-ready architecture; full self-service tenant administration is not required in phase 1 |
| Calendar integration | Relevant for schedules, course runs, interviews and reminders |

### 18.2 Relevant, but should be optional or phase-based

| ERP reference item | SOQ implementation position |
|---|---|
| AI business insights | Optional future analytics capability |
| Demand forecasting | Optional analytics / planning capability |
| Multi-currency support | Optional unless SOQ operationally requires it in real payment/accounting flows |
| Push notifications | Optional notification-channel enhancement |
| Mobile ERP app | Not phase-1 core; responsive web remains the default delivery model |
| Multi-language support | Out of current PRD scope unless commercial scope changes |

### 18.3 Not core to the current SOQ TMS objective

These are generic ERP concepts, but they should not be forced into the SOQ build unless the business explicitly expands scope:

- HR management
- inventory management
- procurement management
- generic sales module beyond CRM / enquiry-to-enrolment

### 18.4 Practical mapping for SOQ

The closest SOQ mapping is:

- **HR module** -> not in current scope
- **Inventory module** -> not in current scope
- **Sales module** -> CRM / admissions conversion flow
- **Procurement module** -> not in current scope
- **Finance module** -> finance core + Xero integration

This keeps the product disciplined: we take the **useful architecture ideas** from the ERP reference, without letting the project drift into a generic ERP build.

## 19. Mapping to a practical AI 7-layer model

There is no single universal "AI 7 layers" standard, so for implementation planning this project should use a practical enterprise mapping:

### Layer 1. Infrastructure

- AWS environment
- PostgreSQL
- Redis
- object storage
- observability and secrets management

### Layer 2. Data

- student records
- course and pricing records
- attendance data
- assessment data
- finance/order data
- documents, evidence and audit logs

### Layer 3. AI/model services

Not core for phase 1, but future-capable:

- OCR / document extraction
- classification
- summarisation
- recommendation
- anomaly detection

### Layer 4. Knowledge / retrieval

Potential future AI knowledge layer:

- policy rules
- funding rules
- course rules
- approval rules
- document retrieval
- audit/evidence lookup

### Layer 5. Orchestration / workflow

This is already important even without advanced AI:

- approval engine
- notification routing
- integration jobs
- queue/event orchestration
- future AI assistant actions under human controls

### Layer 6. Application experience

- Student Portal
- Admin Workspace
- Trainer Portal
- dashboards, reports and operational tools

### Layer 7. Governance and control

- RBAC
- privacy controls
- retention policy
- audit trail
- approval gates
- human review on sensitive actions

### What this means for SOQ

SOQ TMS is **not** an AI-first system in phase 1. It is primarily a **workflow, data and governance platform** with strong future AI extension points.

So the practical mapping is:

- strongest focus now: **Layers 1, 2, 5, 6, 7**
- optional later expansion: **Layers 3 and 4**

That is the right balance. We build the operating system for the business first, then add AI services where they genuinely improve speed, quality or compliance.