# Arquitectura, rutas y datos

## Organización

| Área | Ubicación | Responsabilidad |
| --- | --- | --- |
| Configuración | `package.json`, `vite.config.ts`, `tsconfig.json` | Dependencias, compilación y TypeScript |
| Variables privadas | `src/env.ts`, `.env` | Parámetros de conexión del servidor |
| Presentación | `src/lib/components` | Tarjetas, cuadrícula, breadcrumbs, detalle y estudiantes |
| Tipos | `src/lib/types/escolar.ts` | Contratos de datos que recibe la interfaz |
| Conexión | `src/lib/server/db/index.ts` | Pool mysql2 y cliente Drizzle |
| Esquema de lectura | `src/lib/server/db/schema.ts` | Columnas verificadas que usan las consultas |
| Repositorio | `src/lib/server/repositories/escolar.ts` | Consultas y validación de sede/grado |
| Rutas | `src/routes` | Cargas del servidor y vistas |
| Errores | `src/hooks.server.ts`, `src/routes/+error.svelte`, `src/error.html` | Errores de ruta y fallos de carga |
| Pruebas | `tests/routes.test.mjs` | Pruebas HTTP contra la base local |

## Rutas

| Ruta | Resultado |
| --- | --- |
| `/` | Tarjetas de sedes y selección de año |
| `/sedes/[sedeId]` | Accesos a Grados, Docentes, Asignaturas y Estudiantes |
| `/sedes/[sedeId]/grados` | Grupos de esa sede y año |
| `/sedes/[sedeId]/grados/[gradoId]` | Asignaturas, docentes y matrículas del grupo |
| `/sedes/[sedeId]/docentes` | Directorio de docentes vinculados |
| `/sedes/[sedeId]/asignaturas` | Asignaturas por grupo |
| `/sedes/[sedeId]/estudiantes` | Matrículas de la sede y búsqueda por nombre |

El parámetro de consulta `ano` conserva el código exacto del año en los enlaces de tarjetas y breadcrumbs. Cambiar el año con el formulario lleva a Sedes. La cabecera también tiene un enlace a la raíz sin año.

Sin año se pueden ver las sedes y la pantalla de sede, pero los módulos académicos requieren selección. Un año no registrado genera 400. Una sede inexistente o un grado que no pertenece a la sede/año solicitados genera 404.

## Relaciones utilizadas

1. `sedes.codigo = datoscurso.cod_sede`.
2. `datoscurso` se une a `asignaturas` mediante `ano_lectivo`, `grado` y `curso`.
3. `asignaturas.cod_docente = docentes.cedula`.
4. `datoscurso` se une a `matriculados` mediante `ano_lectivo`, `grado` y `curso`.
5. `matriculados.estado = estado.codigo`.

Estas son las condiciones de los JOIN implementados; no afirman que existan restricciones FOREIGN KEY en la base.

El identificador de sede conserva sus ceros iniciales. El identificador de grado en la URL es `datoscurso.row_id`, validado junto con año y sede. La clave primaria de `datoscurso` observada en los metadatos es compuesta por año, grado y curso.

Las asignaturas y los estudiantes se consultan por separado para no multiplicar matrículas por el número de materias. La lista de materias agrupa los resultados de docentes por identificador de asignatura. Una materia sin correspondencia en el directorio docente sigue visible.

El directorio de docentes incluye quienes tienen adscripción actual a la sede o carga académica en ella durante el año elegido. Las matrículas incluyen todos los estados y muestran su descripción.

## Componentes

- `NavigationCard.svelte`: enlace de tarjeta con título, descripción y etiqueta.
- `CardGrid.svelte`: cuadrícula de una, dos o tres columnas según el ancho.
- `Breadcrumbs.svelte`: enlaces de contexto y página actual.
- `GradeDetails.svelte`: paneles de asignaturas/docentes y estudiantes.
- `StudentList.svelte`: búsqueda por nombre sobre los registros ya cargados, estados y mensajes vacíos.

La búsqueda actual es local, sin paginación del servidor. La aplicación devuelve nombres y datos académicos necesarios para esas vistas; no consulta datos médicos, documentos ni familiares.

## Conexión y errores

Las variables `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER` y `DB_PASSWORD` se mantienen en el servidor. El pool limita las conexiones a cinco y desactiva consultas múltiples en una llamada. Drizzle parametriza los valores de filtro.

Las respuestas académicas usan `Cache-Control: private, no-store`. Los errores inesperados presentan un mensaje genérico al cliente. Esto no sustituye un sistema de autenticación ni establece un historial de auditoría.

El esquema parcial no define la totalidad de las tablas. No ejecutar sincronizaciones de estructura ni migraciones sobre él.