Developer Guide

Welcome to the SIS Developer Guide. This documentation covers system architecture, development setup, and code patterns.

Quick Start

1. Prerequisites - What you need installed
2. Local Setup - Clone and configure
3. Running Servers - Start development

Documentation Sections

Section	Description
Architecture	System design and patterns
Setup	Development environment
Backend	Go backend development
Frontend	Vue 3 + TypeScript
Extending	Adding new features
API Reference	REST API documentation

Tech Stack Overview

Backend

• Language: Go 1.24+
• Router: Standard library net/http (Go 1.22+ routing)
• Database: PostgreSQL (via lib/pq driver)
• Sessions: Valkey/Redis (required, for server-side session storage)
• Auth: Session-based with HttpOnly cookies and CSRF protection
• Validation: go-playground/validator/v10
• Email: net/smtp with custom service wrapper (Mailpit for dev)
• Hot Reload: Air (cosmtrek/air)

Frontend

• Framework: Vue 3.5+ with Composition API
• Language: TypeScript 5.9+
• Build: Vite 7
• UI Library: PrimeVue 4 (Aura theme)
• State: Pinia 3
• Router: Vue Router 4
• HTTP: Axios
• i18n: Vue i18n 11

URLs

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000/api/v1/
Mailpit (email)	http://localhost:8025

Key Concepts

Domain-Driven Design

The backend is organized into 19 packages under internal/domain/:

• academic - Courses, degrees, requirements, scheduling, materials
• audit - Degree progress, graduation tracking, transfer credits
• authentication - Session auth, user management, magic links
• authorization - RBAC, permissions, impersonation, dashboard tiles
• billing - Tuition, fees, payments, refund schedules
• core - Lookups, settings, email templates, currencies
• financialaid - FAFSA, awards, financial estimates
• formbuilder - Dynamic forms for applications
• grading - Grades, GPA, transcripts
• organization - Campuses, buildings, departments, colleges
• people - Person records, demographics, photos
• proxy - Parent/guardian delegated access
• registration - Enrollment, holds, waitlists, planning
• reporting - Reports, IPEDS
• roles - Students, teachers, advisors, cohorts
• sso - SAML identity providers, JIT provisioning
• testscores - Standardized tests, policies, superscoring
• workflow - Registration workflows, automation rules
• workflowengine - Generic configurable approval workflows

One more domain package sits outside internal/domain/:

• internal/lmsintegration - LMS connectors, sync engine, SIS CSV export

It replaced internal/domain/lms wholesale. Migration 199 created the lms schema and 202 dropped the seven legacy records.lms_* tables; the old package is deleted. If you find a reference to internal/domain/lms, it is stale. See LMS Integration Design.

Two of the packages listed above are retired but still present:

• admissions was removed in August 2026; a different system took it over. Its database schema is untouched, and applicant records are still served by roles at /roles/applicants.
• financialaid is deliberately unreachable. Migration 144 deleted its permission nodes and grants, so every route returns 403 — there is no role that can be granted access. The Go package, its routes, authz.KnownNodes entries and the financialaid schema all remain, which is a trap for whoever eventually removes it.

Role-Based Design

Roles are derived from actions:

• Student - Created when registering for classes
• Teacher - Created when assigned to teach
• Advisor - Created when assigned advisees
• Applicant - Created when applying to program

Domain Module Pattern

Each domain follows a consistent structure:

• model.go - Database entity structs
• dto.go - Request/Response DTOs
• repository.go - Data access layer
• service.go - Business logic
• handler.go - HTTP handlers
• routes.go - Route registration

Lookup Values

Reference data stored in individual lookup_* tables (e.g., lookup_program_status):

• Status codes (ACTIVE, INACTIVE, PENDING)
• Type classifications (EMAIL_TYPE, PHONE_TYPE)
• Categories (BLOCK_TYPE, REQUISITE_TYPE)
• Registry in core/lookup_registry.go maps type codes to table names (~110 types)