AIMS — System Architecture

🏛️

aims-core

Central platform — marketing site, school signup, super-admin dashboard. Entry point for all new tenants.

aimsgo.com

🏫

aims (tenant)

Per-school dashboard with 15+ feature modules. Each school runs its own isolated instance.

{school}.aimsgo.com

🛡️

admindash

Internal platform admin — KPIs, analytics, school management and user monitoring.

aimsgo.com/admindash

🧩

aims-apps

Shared standalone HTML apps and brand assets. Synced into aims and aims-core at build time. Includes calendar, template editor, finance, HR manager, guardian portal, and more.

⚙️

aimsgo-argocd-apps

GitOps repository. All Kubernetes and ArgoCD configuration lives here. ArgoCD watches this repo and auto-deploys all changes to the cluster.

2

Repository Structure

Each subdirectory is an independent Git repository. The workspace folder is a parent directory containing all repos but is not itself a Git repo.

Directory	GitHub (current)	GitLab (target)	Purpose
`aims/`	africaone-dev/aims	aims/tenant	Tenant dashboard (Next.js + Django)
`aims-core/`	africaone-dev/aims-core	aims/core	Central platform (Next.js + Django)
`aims-apps/`	africaone-dev/aims-apps	aims/apps	Shared HTML apps + brand assets
`admindash/`	africaone-dev/admindash	aims/admin	Platform admin (Django)
`aimsgo-argocd-apps/`	africaone-dev/aimsgo-argocd-apps	aims/infra	K8s/ArgoCD GitOps config

3

Services & Components

aims-core — Central Platform

Frontend (Next.js)

Marketing landing page, school signup wizard, super-admin dashboard. Runs on port 3000.

Next.js 14TypeScriptTailwind

Backend (Django)

Core API: tenant management, OTP auth, school registry. Triggers tenant deployment via GitHub Actions.

Django 5DRFPostgreSQL

aims — Tenant Dashboard Modules

Module	Description
`students`	Student profiles, enrollment, records
`admissions`	Admissions pipeline and applications
`attendance`	Daily/class attendance tracking
`fees`	Fee structures, invoicing, payments
`exams`	Exam scheduling, results, grading
`timetable`	Class scheduling and timetable management
`hr`	Staff HR, payroll, leave management
`library`	Book catalog, borrowing, returns
`subjects`	Subjects, classes, streams
`clubs`	Student clubs and activities
`meal_plans`	Cafeteria / meal planning
`reports`	Analytics and report generation
`health_wellness`	Student health records (clinic)
`notifications`	In-app and email notifications
`audit`	Audit log for all sensitive actions

aims-apps — External Apps

App	Type	Description
`brand-assets/`	CSS/JS	Shared theme, fonts, logos
`calendar-app/`	HTML App	School calendar interface
`template-editor/`	HTML App	Document/report template designer
`finance-app/`	HTML App	Fee & finance standalone surface
`hr-manager/`	HTML App	HR management standalone surface
`guardian-portal/`	HTML App	Parent/guardian-facing portal
`admissions-portal/`	HTML App	Admissions portal (external-facing)
`comms-hub/`	HTML App	Communications hub
`clinic/`	HTML App	Health/wellness clinic app
`library/`	HTML App	Library standalone app

4

Tech Stack

Frontend

Layer	Technology
Framework	Next.js 14.2.18
Language	TypeScript, React 18
Styling	Tailwind CSS 3.4, SASS
UI Components	Radix UI, Lucide React
Rich Text	TipTap
Charts	ApexCharts, Recharts
Animation	Framer Motion
Export	jsPDF, html2canvas
Runtime	Node.js 20 (Alpine)

Backend

Layer	Technology
Framework	Django 5.0+
REST API	Django REST Framework 3.14
Language	Python 3.11+
Pkg Manager	uv
Auth	Session cookies + SimpleJWT
Storage	boto3 + django-storages
File Processing	Pillow, openpyxl, pdfplumber
Server	Gunicorn

Infrastructure

Component	Technology
Orchestration	Kubernetes
GitOps	ArgoCD (App of Apps pattern)
Ingress	Traefik
TLS	cert-manager + Let's Encrypt
Config Management	Helm 3
DB Pooling	PgBouncer
Secret Replication	Reflector
Image Registry	GHCR → migrating to GitLab Registry
CI/CD	GitHub Actions → migrating to GitLab CI

5

Database Architecture

Hybrid multi-tenancy: a shared core database for platform-wide data and isolated per-tenant databases for each school's data.

Core Database — `aimsgodb`

Shared across the entire platform. Contains schools registry, platform user accounts, authentication sessions, newsletter subscriptions, and deployment status per tenant.

Per-Tenant Database — `{tenant}_db`

One database per school. Contains all school-specific data: students, staff, fees, exams, attendance, timetables, library records, and all module data.

A custom Django database backend (core.db_backend) enforces Row-Level Security, preventing any query from crossing tenant boundaries. PgBouncer runs in the database namespace to pool connections.

6

Infrastructure & Deployment

Kubernetes Namespace Layout

Cluster Layout

Cluster
├── argocd/           — ArgoCD control plane
├── database/         — PostgreSQL + PgBouncer
├── aims-core/        — Central platform (frontend + backend)
├── {tenant-name}/    — One namespace per school
│   ├── frontend deployment
│   ├── backend deployment
│   └── ingress → {tenant}.aimsgo.com
└── ...               — More tenant namespaces

ArgoCD — App of Apps Pattern

root-app.yaml → bootstraps everything └── apps/applicationset.yaml ├── aims-core.yaml → helm-aims-core/values.yaml └── ApplicationSet → helm-template/tenants/ ├── tenant-alpha/values.yaml ├── tenant-beta/values.yaml └── tenant-gamma/values.yaml

Tenant Provisioning Flow

1. School signs up → aimsgo.com 2. aims-core creates school record in aimsgodb 3. aims-core dispatches GitHub Actions workflow action=create-tenant, tenant_name={subdomain} 4. Workflow creates helm-template/tenants/{name}/values.yaml → commits to aimsgo-argocd-apps repo 5. ArgoCD detects commit → deploys new K8s namespace 6. Tenant backend init → POST /api/auth/tenant-bootstrap-ready/ 7. aims-core marks school deployment_ready=true 8. User redirects to {tenant}.aimsgo.com/login

Secrets Management

Secret	Namespace	Notes
`postgres-credentials`	Per namespace	DB username/password
`django-secret`	Per namespace	Django SECRET_KEY
`object-storage-credentials`	aims-core	Reflector mirrors to all namespaces
`resend-api-key`	aims-core	OTP email sending
`github-actions-token`	aims-core	Tenant provisioning trigger
`tenant-bootstrap-secret`	All namespaces	Shared between core and tenant backends

7

Key Flows

User Request Flow

Browser → {tenant}.aimsgo.com └── Traefik Ingress ├── / → Next.js Frontend :3000 │ → Serves HTML/JS/CSS │ → API calls to /api └── /api → Django Backend :8000 → Validates session cookie → Reads/writes to tenant DB → Returns JSON response

aims-apps Sync Flow

aims-apps/ (separate repo) │ ├── npm run sync (or automatic via predev hook) │ ├── → aims/frontend/public/ │ /calendar-app/ /template-editor/ /brand-assets/ │ └── → aims-core/frontend/public/ /user-guide/ /brand-assets/

8

External Integrations

Service	Purpose	Used by
Resend	OTP email delivery for auth	aims-core backend
GitHub Actions API	Trigger tenant provisioning workflow	aims-core backend
Hetzner Object Storage	Media file storage (S3-compatible)	aims + aims-core backends
GHCR	Docker image storage	All services (migrating to GitLab)
Let's Encrypt	Automatic TLS certificates via ACME	cert-manager

9

Environment Configuration

aims-core backend

Variable	Purpose
`DB_*`	Core DB connection
`SECRET_KEY`	Django secret key
`TENANT_BOOTSTRAP_SECRET`	Shared with tenant backends
`GITHUB_TOKEN`	Triggers provisioning
`RESEND_API_KEY`	OTP emails
`OBJECT_STORAGE_*`	Hetzner S3 credentials
`ADMIN_API_KEY`	Admin API auth

aims backend (per tenant)

Variable	Purpose
`CORE_DB_*`	Connection to aimsgodb
`TENANT_DB_NAME`	This tenant's database
`TENANT_BOOTSTRAP_SECRET`	Shared with aims-core
`CORE_BOOTSTRAP_READY_URL`	Callback URL after init
`TENANT_SUBDOMAIN`	School subdomain
`TENANT_SCHOOL_ID`	School ID from core DB
`USE_REMOTE_MEDIA`	Toggle local vs S3

AIMS System Architecture