Skolerom | Automata

// section 01 · descubrimiento

$ cat ./descubrimiento.md

▸ descripcion

Skolerom (app.skolerom.no) es el LMS que usan las escuelas noruegas K-12 para clases, tareas, contenido y evaluaciones. La API en Laravel maneja usuarios, cursos, notas y mapeos de curriculum; MongoDB guarda el contenido flexible y muy editado (drafts de tareas, teaching paths) mientras PostgreSQL (con ltree) almacena la data relacional y jerarquica estructurada. El frontend React renderea las vistas de docente y alumno. La busqueda corre en Elasticsearch. El deploy es un docker-compose por entorno + GitLab CI por repo (back / front / search / devops).

▸ problema

Una plataforma noruega K-12 multi-tenant tiene que modelar el curriculum UDIR nacional, aislar data por colegio, enviar features rapido a traves de tres repos independientes y mantener produccion estable a traves de dev/stage/prod. Hacer esto con un solo store SQL fuerza cambios de schema por cada ajuste de contenido; con un solo Mongo se pierden las garantias transaccionales.

▸ audiencia

Escuelas noruegas K-12, docentes y estudiantes; directores TI que gestionan deploys por colegio.

// section 03 · arquitectura

$ cat ./arquitectura.md

c4 / contenedor · c4-level-2

loading…

flowchart TD
    student(((Student)))
    teacher(((Teacher)))

    front["React 18 SPA<br/><i>teacher + student views</i>"]
    feide["Feide / Dataporten<br/><i>OAuth2 SSO</i>"]

    subgraph aws["AWS"]
        nginx["nginx<br/><i>reverse proxy</i>"]
        api["php-api<br/><i>Laravel 11</i>"]
        worker["php-queue-worker"]
        pg[(PostgreSQL 16<br/><i>ltree · structured</i>)]
        mongo[(MongoDB 4.4<br/><i>drafts · flexible</i>)]
        redis[(Redis 7<br/><i>cache · queue</i>)]
        es[(Elasticsearch<br/><i>curriculum search</i>)]
        s3[(AWS S3<br/><i>files</i>)]
    end

    student --> front
    teacher --> front
    front --> feide
    front -->|HTTPS| nginx
    nginx --> api
    api --> pg
    api --> mongo
    api --> redis
    api --> es
    api --> s3
    api -->|dispatch| worker
    worker --> pg
    worker --> mongo

    classDef person fill:#0D1117,stroke:#4ADE80,color:#E5E7EB
    classDef container fill:#0D1117,stroke:#06B6D4,color:#E5E7EB
    classDef store fill:#111827,stroke:#FBBF24,color:#E5E7EB
    classDef ext fill:#111827,stroke:#6B7280,color:#9CA3AF

    class student,teacher person
    class nginx,api,worker,front container
    class pg,mongo,redis,es,s3 store
    class feide ext

    style aws fill:transparent,stroke:#4ADE80,stroke-dasharray:4 4,color:#E5E7EB

// section 03b · secuencias

$ cat ./secuencias.md

// flujos en runtime — quien habla con quien y en que orden

// Una accion del user que escribe en PostgreSQL (estructurado) y MongoDB (flexible) sin dejar estado parcial.

Escritura cross-store con rollback · flow-01

loading…

sequenceDiagram
    autonumber
    actor Teacher
    participant API as Laravel API
    participant Svc as Store...ValidationService
    participant PG as PostgreSQL
    participant Mongo as MongoDB
    participant Redis

    Teacher->>API: POST /teaching_paths
    API->>Svc: store(payload)
    Svc->>PG: BEGIN
    Svc->>PG: INSERT teaching_paths<br/>(estructurado)
    Svc->>Mongo: upsertDraft(id, flexible)
    alt Mongo OK
        Svc->>PG: COMMIT
        Svc->>Redis: tags(teaching_paths).forget(id)
        Svc-->>API: ok
        API-->>Teacher: 201 Created
    else Mongo falla
        Svc->>PG: ROLLBACK
        Svc-->>API: throw MongoSyncFailed
        API-->>Teacher: 500 (reintento en cola)
    end

// section 04 · infraestructura

$ cat ./infraestructura.md

▸ servicios

provider: Laravel 11 + PostgreSQL + MongoDB + Redis + Elasticsearch en AWS

▸ php-api (HTTP Laravel)
▸ php-queue-worker (cola Laravel)
▸ nginx (reverse proxy)
▸ postgres 16 (relacional + ltree)
▸ mongo 4.4 (contenido flexible)
▸ redis 7 (cache + cola)
▸ elasticsearch (busqueda de curriculum)
▸ S3 (storage de archivos)

// section 05 · implementacion

$ cat ./implementacion.md

▸ frontend

· React 18
· TypeScript
· Redux
· Webpack
· Tailwind

▸ backend

· Laravel 11
· PHP 8.2
· Passport (OAuth2)
· spatie/laravel-permission
· mongodb/laravel-mongodb 4.9
· Doctrine DBAL
· spatie/laravel-fractal

▸ datos

· PostgreSQL 16 con ltree (curriculum jerarquico)
· MongoDB 4.4 (drafts + contenido flexible)
· Redis 7 (cache + colas)
· Elasticsearch (busqueda)
· AWS S3

▸ devops

· Docker Compose con overrides por entorno (dev / staging2 / production / new-production)
· GitLab CI por repo (back, front, search, devops)
· Sentry + Logtail
· Bitbucket Pipelines en algunos repos

// section 06 · desafios tecnicos

$ cat ./challenges/*.md

// 3 problemas tecnicos resueltos

01 / 03

challenge-01.md · multi-store · consistencia · dominio

▸ problema

Mantener PostgreSQL y MongoDB consistentes cuando una sola accion del user (publicar un teaching path) escribe en los dos.

restriccion: No hay transaccion cross-store. Una escritura a MongoDB que falla despues del commit a PostgreSQL deja al sistema reportando un path publicado que el frontend no puede leer completo. Hacerlo en el orden inverso tiene el mismo failure mode simetrico.

▸ enfoque

Toda escritura cross-store pasa por una capa de servicio (ej. StoreTeachingPathValidationService) que hace PostgreSQL primero (transaccional), despues MongoDB. Si MongoDB falla, el servicio rollbackea la fila de PostgreSQL por el mismo use case y emite un evento para la cola de reintentos. El cache (Redis) se invalida ultimo, asi un estado parcial nunca es legible.

app/Service/StoreTeachingPathValidationService.php php

// Patron (simplificado):
DB::transaction(function () use ($payload) {
    $row = TeachingPath::create($payload->structured());   // PostgreSQL
    try {
        $this->mongo->upsertDraft($row->id, $payload->flexible());
    } catch (\Throwable $e) {
        // throw rollbackea la transaccion PG
        throw new MongoSyncFailed($row->id, $e);
    }
    Cache::tags('teaching_paths')->forget($row->id);
});

challenge-02.md · devops · docker · gitlab

▸ problema

Deployar cuatro repos versionados independientemente (back, front, search, devops) a un stack coherente dev / staging / production.

restriccion: Cada repo tiene su pipeline GitLab. Produccion corre en AWS con las mismas imagenes que dev local. La config especifica de entorno no puede filtrarse en la imagen; los rollbacks tienen que poder hacerse sin rebuildear.

▸ enfoque

El repo devops es dueño del docker-compose.yml y un archivo de override por entorno (dev / staging2 / production / new-production). El pipeline GitLab de cada repo de app buildea una imagen, la pushea al registry, y la tagea por commit SHA. El pipeline del repo devops elige el SHA via env var y re-deploya. El frontend buildea a un artefacto estatico que se pushea a S3 y se sirve via nginx.

devops/base/skolerom-devops/docker-compose.yml yaml

services:
  php-api:
    build:
      context: ./../temabok-back
      dockerfile: devops/php-api/Dockerfile
    networks: [backend]

  nginx:
    build:
      context: ./nginx
      dockerfile: Dockerfile
    depends_on: [php-api]

# Override por entorno:
#   docker compose -f docker-compose.yml \
#                  -f environments/dev/docker-compose.dev.yml up --build

challenge-03.md · migrations · schema · ops

▸ problema

Manejar 265 migraciones PostgreSQL + cambios de schema MongoDB sin conflictos cuando dos devs cortan migraciones en paralelo.

restriccion: Las migraciones deben ser idempotentes y correr una vez por entorno. La data UDIR (curriculum nacional) tiene que sembrarse en un orden conocido para que las FKs caigan bien. Dev/stage/prod trackean estado de migracion independientemente.

▸ enfoque

Sistema de migraciones de Laravel para PostgreSQL (ordenado por timestamp, natural). Seeders custom para curriculum UDIR que chequean existencia antes de insertar. Los volumes de Docker Compose persisten estado de DB por entorno, asi los re-runs en dev no destruyen data. CI hace un dry-run migrate contra una copia de staging antes de promover.

database/migrations/ bash

# Levantar el stack dev desde checkout limpio:
docker compose -f docker-compose.yml \
               -f environments/dev/docker-compose.dev.yml \
               up --build

# Las migraciones corren dentro del container php-api al bootear:
php artisan migrate --force
php artisan db:seed --class=UdirCurriculumSeeder

// section 07 · testing & ci

$ cat ./testing.md

▸ estrategia

Suite Pest 3 (36 archivos de test) sobre SQLite in-memory para unit rapido y una capa de integracion aparte que pega a Postgres + MongoDB reales dentro de Docker. Los flujos SSO (Dataporten / Feide / JWT) se testean con JWKS stubeados. Los chequeos de permisos via spatie/laravel-permission tienen unit tests por rol.

▸ herramientas

Pest 3.8PHPUnit (via Pest)Mockery 1.6GitLab CIBitbucket Pipelines

// section 09 · resultados

$ cat ./resultados.md

01 /

2753

commits en el repo de backend

02 /

55

modelos Eloquent

03 /

265

migrations PostgreSQL

04 /

36

archivos Pest

05 /

4

entornos de deploy (dev, staging2, production, new-production)

▸ outcomes

Sistema en produccion sirviendo escuelas noruegas en app.skolerom.no. El backend maneja 265+ versiones de schema entre PostgreSQL + MongoDB. CI deploya en merge a master. El Docker Compose multi-environment permite levantar entornos nuevos con un solo archivo de override.

// section 10 · lecciones

$ cat ./lessons.md

// si lo hiciera de nuevo

01 /
La capa de servicio es la unica frontera segura entre dos stores

Dejar que los controllers escribieran directo a Postgres y Mongo llevaba a estados parciales que el frontend renderaba contento. Canalizar toda escritura cross-store por un solo servicio hizo el failure mode explicito y el path de rollback obvio.
02 /
Overrides de Compose por entorno le ganan a un solo config grande

Al principio el equipo manejaba staging y production en el mismo compose con if-branches. Se rompio en la primera caida real. Partirlo en una base + un override por entorno hizo el diff entre entornos grep-able y los rollbacks un cambio de un archivo.

// menciones

$ grep -r "this-url" ./web

// respuestas, reposts y likes desde la web abierta

▸ reactions

♡ 0 likes

↻ 0 reposts

↩ 0 replies

▸ replies & mentions

// relacionados

$ grep -l "tech" ./projects/*

// proyectos que comparten parte del stack

01 / related

Facturador Electronico SUNAT

SaaS multi-tenant de facturacion electronica para Peru: emite los seis comprobantes SUNAT via Greenter con cola async, aislamiento por tenant y API REST publica.

Laravel 11

02 / related

CEO Sim

Juego multiplayer de simulacion empresarial embebido en Moodle/Canvas/Blackboard via LTI 1.3 — auto-provisiona users, deep-link a rondas, sincroniza notas via AGS.

Docker Compose

> Skolerom

$ cat ./descubrimiento.md

$ cat ./arquitectura.md

$ cat ./secuencias.md

$ cat ./infraestructura.md

$ cat ./implementacion.md

$ cat ./challenges/*.md

Mantener PostgreSQL y MongoDB consistentes cuando una sola accion del user (publicar un teaching path) escribe en los dos.

Deployar cuatro repos versionados independientemente (back, front, search, devops) a un stack coherente dev / staging / production.

Manejar 265 migraciones PostgreSQL + cambios de schema MongoDB sin conflictos cuando dos devs cortan migraciones en paralelo.

$ cat ./testing.md

$ cat ./resultados.md

$ cat ./lessons.md

La capa de servicio es la unica frontera segura entre dos stores

Overrides de Compose por entorno le ganan a un solo config grande

$ grep -r "this-url" ./web

$ grep -l "tech" ./projects/*

Facturador Electronico SUNAT

CEO Sim

$ automata deploy --tu-operacion

navigation

case study

diagrams