Docs

Public technical
documentation.

The guides we work with at AULAS LATAM: conventions, API design, security, frontend, data and AI. Use them, cite them or suggest improvements.

9
Guides
v1.0
Version

Introduction

This documentation describes how we build software across the AULAS LATAM ecosystem. It follows the Diátaxis framework: tutorials to learn, how-to guides to get tasks done, reference to look things up and explanations to understand the why.

The guides are binding for AULAS LATAM projects and free for anyone to consult. When a rule has an exception, the exception is recorded in an ADR.

Keywords. “Must” marks a mandatory rule; “should”, a strong recommendation that allows justified exceptions; “may”, an option.

Code conventions

The goal is that anyone on the team can read, review and change any repository without friction.

  • Every repository must include .editorconfig, a formatter and a linter, run in continuous integration.
  • Names must describe intent: calculateCheckDigit, not calc2.
  • Code identifiers may be in English or Spanish, but not mixed within the same module.
  • Commit messages follow Conventional Commits.

Commit messages

feat(api): agrega paginación por cursor en /eventos
fix(auth): corrige expiración de sesión en Safari
docs(readme): documenta variables de entorno
refactor(pagos): separa conciliación del webhook
chore(deps): actualiza dependencias de desarrollo

# Cambio incompatible:
feat(api)!: elimina el parámetro "page" en favor de "cursor"

Git flow and review

We work with short-lived branches off main. Every change arrives through a pull request and main must always be deployable.

  • Branches: feat/…, fix/…, docs/…. Ideally they live under three days.
  • Small pull requests: if a review takes more than 30 minutes, it should probably be split.
  • At least one approval from someone else; two for changes to authentication, payments or personal data.
  • CI must pass before merging: tests, lint, static analysis and dependency audit.

Pull request checklist

- [ ] Describes the problem and the solution
- [ ] Includes tests or explains why they don't apply
- [ ] Updates affected documentation
- [ ] Introduces no secrets or personal data
- [ ] Considers accessibility and performance (if there's UI)

API design

We design contract-first: the OpenAPI 3.1 contract is reviewed before the implementation is written and is the source of truth for clients and tests.

  • Plural, lowercase resources: /v1/events, /v1/events/{id}.
  • Major version in the path (/v1). Compatible changes don’t bump it.
  • Cursor pagination for growing collections; never return unbounded collections.
  • Dates in ISO 8601 with time zone; amounts as integers in the currency’s minor unit.
  • Errors as Problem Details (RFC 9457), with Content-Type: application/problem+json.

Error example

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://aulas.dev/docs/errores/validacion",
  "title": "Invalid data",
  "status": 422,
  "detail": "start_date must be earlier than end_date.",
  "instance": "/v1/eventos/8f2c",
  "errors": [{ "pointer": "/fecha_inicio", "code": "rango_invalido" }]
}

Security

Security is a requirement, not a phase. We use OWASP ASVS as the controls reference and the OWASP Top 10 for LLM Applications for AI systems.

Release standard

ControlWhat is required
threat_modelThreat model (STRIDE) for every epic or architecture change.
sast_scanStatic analysis with no open critical or high findings.
dependency_auditNo known critical vulnerabilities in dependencies; exceptions documented with a review date.
sbom_generatedSBOM in CycloneDX or SPDX format attached to every release.
tests_passedAutomated tests green, including authorization tests.
docs_publishedUsage, operations and change documentation up to date.
peer_reviewReview by at least one other person; two in sensitive areas.

Ground rules

  • Secrets never go in the repository: use environment variables or a secrets manager.
  • Least privilege for people, services and AI agents; agents don’t take irreversible actions without human confirmation.
  • HTTPS everywhere (.dev domains require it because they are on the HSTS preload list).
Found a vulnerability? Write to us privately at [email protected] before disclosing it. We will respond and coordinate the fix.

PWA and frontend

We build for mid-range phones and patchy connections, which is the reality across much of Latin America.

  • Accessibility WCAG 2.2 level AA: contrast, visible focus, keyboard navigation and alt text.
  • Core Web Vitals at the 75th percentile: LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1.
  • Respect prefers-reduced-motion: animations are optional, content is not.
  • Service worker with an explicit strategy: network-first for pages, cache-first for versioned assets, an offline page.
  • Fonts and assets self-hosted, with no third-party trackers by default.

Data and responsible AI

Personal data processing in Colombia is governed by Law 1581 of 2012. On top of that, we apply these rules to any AI system:

  • Minimization: only data needed for the stated purpose is collected.
  • Prototypes and challenges use synthetic or anonymized data, never real client data.
  • Every AI feature has a documented evaluation: metrics, test set and known limitations.
  • Human review for decisions affecting people’s rights, money or reputation.
  • Users must know when they are interacting with an automated system.

Decision records (ADR)

Every relevant architecture decision is recorded in docs/adr/ with sequential numbering. An ADR is never edited: if the decision changes, a new one supersedes it.

# ADR-0000: Short decision title

Status: Proposed | Accepted | Superseded by ADR-XXXX
Date: YYYY-MM-DD

## Context
What problem or force requires a decision?

## Options considered
1. Option A — pros / cons
2. Option B — pros / cons

## Decision
We chose ... because ...

## Consequences
What gets easier, what gets harder, which risks we accept.

Deployment and operations

  • Three environments: development, staging and production. Staging mirrors production with test data.
  • Every deployment has a tested rollback plan and is announced with its version and CHANGELOG.
  • Automated backups with periodically verified restores.
  • Incidents: detect, contain, communicate and learn with a blameless postmortem.
See something to improve? These guides evolve with the community. Suggest changes through Community.

Documented
means done.

If you work with these standards, you already speak our teams’ language.