Skip to main content

Engineering Priorities

Evalium — Engineering Maturity & Platform Hardening Priorities

This document captures long-term engineering priorities for Evalium’s backend and platform infrastructure. It does not describe features, architecture, or coding rules — those live in:

  • docs/architecture/architecture (structure of the system)
  • docs/architecture/FOUNDATION.md (rules, patterns, invariants)
  • docs/security/roles-and-access-control.md (RBAC model)
  • docs/product/CORE-PLATFORM-ROADMAP.md (product roadmap)

Instead, this file explains how Evalium should evolve on the engineering side as the system scales: performance, reliability, operational excellence, and technical investments.

1. Purpose

Evalium enforces enterprise-safe invariants from Day 1. While our initial UI targets SMBs, the database schemas, RLS enforcement, and scoring engine are built so they can scale later without rewrites. We activate enterprise operations as load requires, not by default.

This guide outlines engineering priorities that keep the system maintainable as both usage and developer headcount increase.

2. Priority Tiers Overview

Tier 1 — Near-term (0–12 months)​

Stabilisation, correctness, and core platform strength. Directly supports the backend-first architecture.

Tier 2 — Mid-term (12–24 months)​

Scaling: performance, caching, indexing, reporting optimisation.

Tier 3 — Long-term (24+ months)​

Advanced optimisations, multi-region, ML features, distributed grading.

These tiers represent engineering investment, not customer-facing features.

Section 2.3: Implementation Phasing​

Development must follow the Primitives First rule defined in the Implementation Phasing & Maturity Plan.

No feature may be activated in the UI (Phase C) until:

  • All required Phase A platform primitives are enforced centrally
  • The feature has passed the Uniformity Check
  • Any relevant Phase B assurance semantics are documented, even if not yet implemented

This ensures Evalium evolves with a single, uniform foundation of truth and prevents UX-led shortcuts from weakening defensibility or market breadth.

3. Tier 1 Priorities (0–12 months)

Strengthen the foundation to guarantee correctness, reliability, and future scalability.

3.1 Modular design & layered architecture​

  • Maintain the handler → service → TxManager → sqlc pattern
  • Keep services small and domain-focused
  • Maintain clear boundaries for adding new modules

3.2 Schema discipline​

  • Every new table:

    • must have tenant_id, org_unit_id, RLS policies
    • must index tenant + org
    • must align with versioning + snapshot rules

  • Prefer additive migrations

  • Avoid schema churn that breaks versioned content

  • Execution ledger enforcement gates and acceptance criteria: docs/architecture/LEDGER-BOUNDARY-AND-ENFORCEMENT.md

  • Write budget rule: every new feature must declare its write path (tables touched, expected write rate, and whether any execution-ledger tables are written). If the writes are non-forensic and heavy, default to async/outbox or a projection table.

3.3 TxManager-first & RLS enforcement​

  • All DB access must go through the scoped transaction model

  • Ensure no regressions via Go tests and linting

  • Strengthen test coverage for:

    • tenant isolation
    • org-unit scoping
    • global admin behaviour

3.4 OpenAPI / API Contract Discipline​

  • API definitions must stay stable
  • Avoid breaking changes; version endpoints when needed
  • Keep API cookbook in sync with backend behaviour

3.5 Observability & Logging (MVP)​

  • Add structured logging (request id, user id, tenant id, org id)

  • Add basic audit events for:

    • new version creation
    • session creation
    • submissions
    • assignment issuance

  • Error logs must distinguish:

    • RLS violations
    • capability errors
    • invalid requests

3.6 Transactional outbox (hard rule for external I/O)​

  • No external I/O inside a DB transaction that writes execution-ledger rows.
  • All external calls (email, storage finalisation, webhooks, xAPI) must go through an outbox + worker.
  • Workers must be idempotent and replay-safe.

4. Tier 2 Priorities (12–24 months)

Scaling: performance, caching, reporting.

4.1 High-volume read optimisation​

  • Add:

    • Postgres read replicas
    • connection pool tuning
    • server-side caching of role → capabilities mapping

4.2 Reporting performance strategy​

  • Introduce a read-optimised reporting projection:

    • flattened submission + item + tags + metadata
    • partitioned by tenant or created_at (metrics-gated; only after usage patterns justify it)

  • Enables:

    • BI dashboards
    • fast filtering
    • multi-tag analysis
    • large assessment cohorts

4.3 Caching​

  • Retryable queue/caching layer (Redis) for:

    • magic link token state
    • role/capability caches
    • heavy preview endpoints

4.4 Capacity planning​

  • Stress-test compute-heavy components (scoring, analytics)
  • Begin modelling batch vs. streaming if needed

5. Tier 3 Priorities (24+ months)

Strategic, long-term engineering investments.

5.1 Horizontal scaling & multi-region​

  • Multi-region database
  • S3 or equivalent for snapshots (optional)
  • Reduce cross-region latency for global tenants
  • Eventual multi-region failover

5.2 Distributed grading / parallel scoring​

  • Large evaluations may require:

    • worker pools
    • job queues
    • coarse-grained scoring operations

  • Could run as:

    • Kubernetes jobs
    • serverless lambdas
    • or internal worker cluster

5.3 ML / semantic features​

Optional enhancements (post-scale):

  • tagging suggestions for authors
  • difficulty estimation
  • distractor effectiveness
  • vector search for question banks
  • adaptive testing support (CAT)

6. Cross-cutting Concerns to Maintain

6.1 Testing discipline​

  • Shell tests for behavioural verification
  • Go integration tests for scoped RLS + API correctness
  • Snapshot tests for previews and submissions
  • All new modules require test coverage before UI usage

6.2 Documentation discipline​

  • Keep:

    • docs/architecture/architecture
    • docs/architecture/FOUNDATION.md
    • docs/security/roles-and-access-control.md
    • docs/product/ENGINEERING_PRIORITY_GUIDE.md up to date

6.3 Developer onboarding​

  • Ensure onboarding guide includes:

    • how to run org silo tests
    • how to use TxManager
    • how to generate new versioned objects
    • how to use the API Cookbook

7. Summary

Evalium’s engineering priorities ensure:

✔ Correctness and security first ✔ Stable, scalable architecture ✔ Predictable evolution path ✔ Ability to onboard additional engineers safely ✔ Space for growth into analytics & enterprise capabilities

This guide sits alongside:

  • docs/architecture/architecture → What Evalium is (structure)
  • docs/architecture/FOUNDATION.md → How we build safely (rules + invariants)
  • docs/product/CORE-PLATFORM-ROADMAP.md → What we build for customers

Use this file when planning technical strategy, discussing engineering investments, or estimating long-term roadmap work.