Skip to content

Architecture Overview

This document describes the current architecture of the Wippidu Kita App as of February 2026.

Tech stack

Component Technology Version
Language Go 1.24.0
Web framework Gin latest
ORM GORM latest
Production DB PostgreSQL / MySQL —
Test DB SQLite (in-memory) —
Templates Go html/template stdlib
i18n Custom (JSON-based) —
Auth JWT (HS256, cookie-based) 7-day expiry

Codebase at a glance

Layer Files Description
Controllers 44 HTTP handlers with dual HTML/JSON responses
Services 23 Business logic, email, scheduling, sync
Middleware 7 Auth, rate limiting, language, approval
Templates 106 Server-rendered HTML pages
Test files 63 ~950 test functions

Dual HTML/JSON API

Every endpoint serves both server-rendered HTML and JSON API responses. The controller determines the format using shouldReturnJSON(c), which checks for:

  1. Route prefix: /api/v1/... returns JSON
  2. Accept header: application/json returns JSON
  3. Otherwise: returns HTML
Browser ──► GET /en/children/1 ──► ChildHandler ──► HTML template
Mobile  ──► GET /api/v1/en/children/1 ──► ChildHandler ──► JSON response

Route registration happens in two places in internal/route/auth.go:

  • MainRoutes() — HTML routes under /:lang/...
  • APIRoutes() — JSON routes under /api/v1/:lang/...

Both call the same controller handlers.

Authentication

  • Method: JWT tokens stored in HTTP-only cookies
  • Algorithm: HS256
  • Expiry: 7 days
  • Flow: Login sets a cookie → middleware extracts and validates → sets User in Gin context
  • API tokens: Separate Bearer token system for intranet sync API (/api/intranet/...)

Authorization

Six roles in hierarchical order:

Role Access scope
Anonymous Public pages only
Parent Own children, own messages/letters
Employee All children at assigned locations
GroupLead Employee access + create letters for group
LocationLead GroupLead access + location-wide letters, access time management
Admin Full system access

Access is location-scoped: all staff at a location can see all children at that location. See Authorization Model for details.

Middleware stack

Middleware File Purpose
authorization.go JWT validation, user loading Sets User in context
api_token.go Bearer token auth for intranet API Sets apiToken in context
force_password_change.go Redirects users with temporary passwords —
language.go Detects language from URL/cookie Sets lang in context
ratelimit.go Rate limiting on sensitive endpoints —
require_approval.go Blocks unapproved accounts —

Features

Communication

  • Parental letters — Review workflow (draft → pending_review → approved → published), interaction types (informal, answer_possible, answer_required), polls, surveys, fill-in tables, file attachments, deadlines
  • Parent messages — Direct employee-to-parent messaging per child, response tracking
  • Employee chat — Internal messaging between staff
  • News — Blog-style announcements scoped to group/location/global, read tracking

Child management

  • Absence notifications — Parents report illness/vacation/other with date ranges, employee acknowledgment
  • Child clusters — Grouping children by time-of-day (today/tomorrow views)
  • Location children — Staff view of all children at their location(s)

Administration

  • User management — CRUD, role assignment, impersonation
  • Child management — CRUD, group assignment, parent linking
  • Delegation — GroupLeads/LocationLeads can delegate letter-writing to other staff
  • Bulk invitations — Invite multiple parents/employees at once
  • Enrollment management — Track child enrollments
  • API token management — Create/revoke tokens for intranet sync
  • Sync dashboard — Trigger and monitor intranet data processing
  • Email settings — SMTP configuration, templates
  • FAQ and legal settings — Configurable content pages

Infrastructure

  • Intranet sync — Two-phase data import (API → staging → app tables)
  • Email — Full SMTP with retry, HTML templates, opt-in per notification type
  • Calendar — Calendar views with events
  • Archive — Historical data access
  • Registration — Self-service with intranet data lookup
  • Changelog — Version history display

Key services

Service Purpose
email.go SMTP sending with retry
email_notifications.go Notification dispatch per type
sync_processor.go Staging → app table transformation
parental_letters.go Letter workflow, response aggregation
scheduler.go Periodic background tasks
reminder_scheduler.go Scheduled reminders
child_cluster.go Time-based child grouping
registration.go Self-service registration flow
employee_invitation.go Bulk employee invitation

Database

The database schema is documented in Database Schema (Current). Key entity groups:

  • Core: User, Child, Location, Group, LocationDevice
  • Auth: Role, Passwd, Pin, Permissions, APIToken
  • Messaging: ParentalLetter, Message, MessageTemplate, News
  • Documents: Document, BlackboardDocument
  • Staging: 9 sync_* tables for intranet data
  • Care: CareDay, AbsenceNotification

All models use GORM's gorm.Model base (ID, CreatedAt, UpdatedAt, DeletedAt with soft delete).