Proposed Directory Structure

Purpose

This is the proposed codebase layout for SOQ TMS — aligned with Implementation Documentation v1 (modular monolith, Laravel + PostgreSQL + React, Redis queues).

Andy Koh (CTO) leads the build against this structure from design sign-off. Squad levels: 1.3 CRD Parties.

---

Repository overview

soq-tms/                              # Monorepo root
├── README.md
├── docs/                               # CRD, PRD, ADRs, runbooks (this package)
│   ├── SOQ_TMS_PRD_v1.1_clean.md
│   ├── SOQ_TMS_Implementation_Documentation_v1.md
│   └── adr/                            # Architecture decision records
│
├── apps/                               # User-facing React applications
│   ├── public-web/                     # Course catalogue, enquiry, registration entry
│   ├── student-portal/                 # Learning, attendance, payments, certificates
│   ├── admin-workspace/                # TMS, CRM, admissions, finance, reporting
│   └── trainer-portal/                 # Roster, delivery, attendance, marking, fees
│
├── packages/                           # Shared frontend / tooling
│   ├── ui/                             # Design system (tokens, shadcn-style components)
│   ├── api-client/                     # Typed REST client generated from OpenAPI
│   ├── auth/                           # Session, Singpass redirect helpers
│   ├── forms/                          # Zod schemas shared with backend DTOs
│   ├── config-eslint/
│   └── config-typescript/
│
├── services/
│   └── api/                            # Laravel modular monolith (system of record)
│       ├── app/
│       │   ├── Http/
│       │   ├── Providers/
│       │   └── Support/                # Cross-cutting helpers
│       │
│       ├── modules/                    # Domain modules (bounded contexts)
│       │   ├── Platform/               # Tenant, org, RBAC shell
│       │   ├── Identity/               # Users, Singpass, MFA, consent
│       │   ├── Catalogue/              # Programmes, courses, modules, fees
│       │   ├── Scheduling/             # Runs, intakes, venues, conflicts
│       │   ├── Admissions/             # Applications, offers, exemptions
│       │   ├── Enrolment/              # Student 360, status, class assignment
│       │   ├── Attendance/             # Sessions, QR, verification, SWDA feed
│       │   ├── Assessment/             # Marks, moderation, release
│       │   ├── Certification/          # Completion, certificates, transcripts
│       │   ├── Finance/                # Orders, subsidies, SFC, refunds
│       │   ├── Crm/                    # Leads, opportunities, Privyr import
│       │   ├── Commission/             # Agent commission, clawback
│       │   ├── Notify/                 # Email, SMS, in-app templates
│       │   └── Audit/                  # Activity log, PII access log
│       │
│       ├── integrations/               # External systems (isolated adapters)
│       │   ├── SwdaHub/                # Queue, retry, ops dashboard APIs
│       │   │   ├── Adapters/
│       │   │   ├── Jobs/
│       │   │   └── Mappers/
│       │   └── Xero/                   # Contacts, invoices, payments, bills
│       │
│       ├── database/
│       │   ├── migrations/             # Per-module migration folders
│       │   └── seeders/
│       │
│       ├── routes/
│       │   ├── api.php
│       │   └── modules/                # Module route registration
│       │
│       └── tests/
│           ├── Unit/
│           ├── Feature/
│           └── Integration/            # SWDA/Xero contract tests (sandbox)
│
├── workers/                            # Optional: dedicated queue workers profile
│   └── integration-worker/             # SWDA + Xero job consumers
│
├── infrastructure/
│   ├── docker/                         # Local dev compose (api, postgres, redis)
│   ├── terraform/                      # AWS SG region (dev, staging, prod)
│   └── ci/                             # GitHub Actions / build pipelines
│
└── tools/
    ├── openapi/                        # API spec generation
    └── scripts/                        # Migrations, Privyr import, seed data

---

Path ownership notes

Path focus (not a role/level matrix — see 1.3 CRD for squad):

---

Key conventions

1. One module = one folder under modules/ with its own Models, Services, Events, Policies, Routes.
2. Integrations never live inside UI apps — only through integrations/ + queue workers.
3. Shared types — Zod/OpenAPI schemas are the contract between services/api and packages/api-client.
4. Events over direct calls — cross-module side effects via domain events + queue (Redis).
5. Feature flags — optional modules (CRM, Commission, advanced analytics) toggled per tenant config.

---

Environment layout

---

Related sections