Shule / my‑school

What is Shule?

Shule (Swahili: school) is a vertically integrated school management system designed specifically for East African K-12 schools, covering the full operational lifecycle from student admissions to leaving certificate generation. It runs as a SaaS platform on my-school.co.ke, with each customer school receiving an isolated tenant environment.

The platform replaces fragmented point solutions (separate fee-collection apps, paper registers, SMS-only parent communication, spreadsheet timetables) with a unified system where student records, academic results, attendance, fees, HR, and communications share a single source of truth. Events flow between modules: an absence automatically triggers a parent SMS; a fee payment updates a student's ledger and the bursar's dashboard simultaneously; a published report card queues PDF delivery to all guardians.

Market positioning

Key differentiators vs. generic SIS products

System design

Shule is a microservices system: 14 independent FastAPI services, each owning a bounded domain, communicating via NATS JetStream for async events and a PostgreSQL-backed outbox for guaranteed delivery. A Next.js 15 frontend and an Expo mobile app consume the services through a typed API layer.

Multi-tenancy model

Each school is a completely isolated PostgreSQL schema named t_{tenant_slug}. This is schema-per-tenant isolation: stronger than row-level filtering and weaker than a separate database. Every table for a school's data lives in that schema; migrations run against all tenant schemas in sequence, guarded to be idempotent.

The platform schema shule_system holds the tenant registry, billing records, platform audit log, and operator CRM. The Caddy reverse proxy reads the subdomain (demo.my-school.co.ke) and passes the tenant slug as an HTTP header; the TenantSession dependency in each service resolves this header to the correct schema for every query.

Technology stack

Service-by-service capabilities

Each service is a standalone FastAPI application with its own database models, business logic, and REST API. Services communicate synchronously via HTTP (internal calls) and asynchronously via NATS JetStream events published through a transactional outbox.

Core — Students, Staff & School Administration

Academic — Timetable, Marks, Report Cards & Curriculum

Timetable engine

The solver uses a constructive + simulated-annealing algorithm, deterministic by seed. It consumes teacher availability constraints, subject requirements per class, room types, and double-period rules. Clash validation uses CP-SAT. TSC teaching-load constraints (maximum lessons per teacher) are enforced at publish time.

Marks, reports & CBC

Attendance — Register, Biometric & Analytics

Fees & Finance — Invoicing, Payments & Reporting

Fee management

Payment rails

Defaulter management & collections

Procurement & bookshop

Human Resources

Communications

Safeguarding, Behaviour & SEND

Library

Facilities, Assets & Visitors

Sports & Co-curricular

Reports & Documents

Scheduler & Workflow Automation

A Temporal worker service manages all time-based and event-driven workflows: automated attendance session creation, fee dunning, cover assignment, timetable scaffolding, and overdue notifications.

Portals by role

The Next.js 15 frontend routes users into distinct portal experiences based on their Keycloak role. All portals share a single deployment: the subdomain identifies the school, and the role determines the navigation tree and accessible pages.

Mobile app (Expo)

The Expo mobile app (iOS and Android) mirrors the teacher and parent portals, with offline capability for attendance marking and gradebook entry. Marks queued offline sync automatically when connectivity is restored.

USSD access

Fee balance enquiry and payment status are accessible via USSD short code (*384# pattern) using Redis-backed session state, enabling parents with feature phones to check balances without the web app.

Predictive intelligence

The AI service routes to LiteLLM (self-hosted on , proxying Claude/GPT/Llama based on configuration). AI features are additive; the platform operates fully without them if the LiteLLM endpoint is unreachable.

External systems & standards

Government education management systems

EdTech standards

Webhooks & event delivery

Schools can register outbound webhooks for any NATS event type. The delivery subsystem retries failed deliveries, maintains a delivery log with per-attempt status, and exposes a retry endpoint for manual replay.

API access

All service APIs follow REST conventions with JSON request/response bodies, UUIDv7 identifiers, and ISO 8601 timestamps. Authentication uses OAuth 2 Bearer tokens issued by Keycloak. Each service exposes OpenAPI docs at /docs (non-production environments). Rate limiting is handled at the Caddy layer.

Security architecture

Authentication & authorisation

Data isolation

Compliance features

Hosting & deployment

The platform runs on a fleet of Contabo (EU) dedicated servers. The production app server is separate from the database host; a hot-standby replica runs continuously.

Deployment model

Observability

Every FastAPI service exposes Prometheus metrics at /metrics. Grafana () aggregates request rate, latency, error rate, and custom business metrics (invoice volume, attendance rates, NATS event lag). Loki collects structured JSON logs from all services. Sentry captures unhandled exceptions in both Python services and the Next.js frontend.

Roles, ports & conventions

RBAC role reference

Service port map

API conventions

Event subjects (NATS)

Consumer services subscribe to relevant subject patterns. Failed deliveries land in shule.dlq.* subjects, visible and replayable via the platform console.