{"id":25825674,"url":"https://github.com/mhuancho/school-api","last_synced_at":"2026-04-18T13:33:17.934Z","repository":{"id":267049073,"uuid":"900069141","full_name":"mhuancho/school-api","owner":"mhuancho","description":"Sistema de Gestión Escolar (School Management System)","archived":false,"fork":false,"pushed_at":"2024-12-08T06:21:08.000Z","size":140,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"desa","last_synced_at":"2025-10-21T19:38:42.196Z","etag":null,"topics":["java","java-17","json","jwt-auth","jwt-authentication","jwt-token","keycloak-client","metadata","panache-entity","panache-repository","postgresql-database","quarkus-maven"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mhuancho.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-07T19:23:34.000Z","updated_at":"2024-12-08T06:21:12.000Z","dependencies_parsed_at":"2024-12-08T00:21:29.105Z","dependency_job_id":"6c67ba30-6314-45e0-9b01-e57c0df6de40","html_url":"https://github.com/mhuancho/school-api","commit_stats":null,"previous_names":["cursosinformaticas/school-api","mhuancho/school-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mhuancho/school-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhuancho%2Fschool-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhuancho%2Fschool-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhuancho%2Fschool-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhuancho%2Fschool-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhuancho","download_url":"https://codeload.github.com/mhuancho/school-api/tar.gz/refs/heads/desa","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhuancho%2Fschool-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31971488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","java-17","json","jwt-auth","jwt-authentication","jwt-token","keycloak-client","metadata","panache-entity","panache-repository","postgresql-database","quarkus-maven"],"created_at":"2025-02-28T14:06:37.972Z","updated_at":"2026-04-18T13:33:17.918Z","avatar_url":"https://github.com/mhuancho.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gestión Escolar\n\nEl Sistema de Gestión Escolar es una plataforma integral diseñada para administrar todos los aspectos de una institución educativa. Proporciona herramientas para gestionar estudiantes, maestros, cursos, asignaturas, horarios, eventos, calificaciones, asistencias y tutores, garantizando una organización eficiente y centralizada. El sistema permite registrar, consultar, actualizar y organizar información académica y administrativa de manera estructurada, optimizando los procesos escolares.\n\n#TABLA RELACIONADA\n```sql script\n1. TABLA ALUMNO\nPropósito: Almacenar información personal y académica de los estudiantes.\nRelaciones:\nanio_escolar: Indica el año académico en el que está inscrito el alumno.\ntutor: Asocia un tutor al estudiante.\ncurso_alumno: Relaciona al alumno con los cursos en los que está inscrito.\ncalificacion: Registra las calificaciones del alumno en exámenes.\nasistencia: Administra el registro de asistencia del alumno.\nevento_alumno: Relaciona al alumno con los eventos escolares en los que participa.\n\n2. TABLA CURSO\nPropósito: Definir los cursos ofrecidos por la institución.\nRelaciones:\ngrado_escolar: Indica el nivel académico (grado) al que pertenece el curso.\nmaestro: Asocia un maestro responsable del curso.\ncurso_alumno: Relaciona alumnos inscritos en el curso.\nasignatura: Define las asignaturas impartidas dentro del curso.\nasistencia: Registra la asistencia de los estudiantes al curso.\n\n3. TABLA ASIGNATURA\nPropósito: Administrar las asignaturas ofrecidas en cada curso.\nRelaciones:\ncurso: Asigna las materias a un curso específico.\nexamen: Vincula los exámenes realizados en esa asignatura.\nhorario: Establece los horarios de clases para cada asignatura.\n\n4. TABLA EXAMEN\nPropósito: Registrar los exámenes programados para cada asignatura.\nRelaciones:\nasignatura: Indica la asignatura a la que pertenece el examen.\ncalificacion: Registra los puntajes obtenidos por los alumnos en este examen.\n\n5. TABLA CALIFICACION\nPropósito: Almacenar las notas obtenidas por los estudiantes en los exámenes.\nRelaciones:\nexamen: Identifica el examen asociado.\nalumno: Registra el estudiante que obtuvo la calificación.\n\n6. TABLA HORARIO\nPropósito: Planificar los horarios de las clases impartidas.\nRelaciones:\nasignatura: Relaciona el horario con la asignatura impartida.\naula: Define el aula donde se imparte la clase.\n\n7. TABLA AULA\nPropósito: Administrar las aulas disponibles para las actividades académicas.\nRelaciones:\nhorario: Asigna las aulas a los horarios de las clases.\n\n8. TABLA MAESTRO\nPropósito: Almacenar información de los maestros de la institución.\nRelaciones:\ncurso: Asocia al maestro con los cursos que imparte.\nevento_maestro: Relaciona al maestro con los eventos en los que participa.\n\n9. TABLA TUTOR\nPropósito: Representar a los tutores legales o responsables de los alumnos.\nRelaciones:\nalumno: Indica a los alumnos bajo la tutela del tutor.\n\n10. TABLA ANIO_ESCOLAR\nPropósito: Administrar los años académicos activos en la institución.\nRelaciones:\nalumno: Asocia a los alumnos con un año escolar específico.\n\n11. TABLA GRADO_ESCOLAR\nPropósito: Definir los niveles académicos (grados) de la institución.\nRelaciones:\ncurso: Relaciona los grados escolares con los cursos ofrecidos.\n\n12. TABLA ASISTENCIA\nPropósito: Registrar la asistencia de los alumnos a los cursos.\nRelaciones:\nalumno: Indica el estudiante cuya asistencia se registra.\ncurso: Asocia la asistencia con un curso específico.\n\n13. TABLA EVENTO_ESCOLAR\nPropósito: Registrar eventos organizados por la institución educativa.\nRelaciones:\nevento_alumno: Relaciona alumnos participantes en el evento.\nevento_maestro: Relaciona maestros participantes en el evento.\n\n14. TABLA EVENTO_ALUMNO\nPropósito: Relacionar alumnos con los eventos escolares.\nRelaciones:\nevento_escolar: Indica el evento al que pertenece.\nalumno: Asocia al alumno participante.\n\n15. TABLA EVENTO_MAESTRO\nPropósito: Relacionar maestros con los eventos escolares.\nRelaciones:\nevento_escolar: Indica el evento al que pertenece.\nmaestro: Asocia al maestro participante.\n\n16. TABLA CURSO_ALUMNO\nPropósito: Relacionar alumnos con los cursos en los que están inscritos.\nRelaciones:\nalumno: Indica el estudiante inscrito.\ncurso: Relaciona el curso correspondiente.\n```\n\n## SCHEMA\n![quarkus_db.png](quarkus_db.png)\n## Running the application in dev mode\n\nYou can run your application in dev mode that enables live coding using:\n\n```shell script\n./mvnw compile quarkus:dev\n```\n\n## Resumen\nEste sistema está diseñado para proporcionar una gestión completa de las operaciones escolares, facilitando la administración de datos relacionados con estudiantes, maestros, cursos, eventos y otras actividades académicas. Las relaciones entre las tablas aseguran la consistencia y la integración de la información en todas las áreas de la institución educativa.\n\n- REST resources for Hibernate ORM with Panache ([guide](https://quarkus.io/guides/rest-data-panache)): Generate Jakarta\n  REST resources for your Hibernate Panache entities and repositories\n\nquarkus dev\n./mvnw quarkus:dev\n\n\nmvn -N wrapper:wrapper\n\n## Dependencias del Proyecto\nDescripción:\nEl proyecto utiliza Maven para la gestión de dependencias, y está basado en Quarkus, un framework diseñado para aplicaciones Java nativas en la nube y de alto rendimiento. A continuación, se documentan las dependencias incluidas en el archivo pom.xml, categorizadas por su propósito.\n```sql script\n1. Gestión de Dependencias (dependencyManagement)\n   Esta sección centraliza la gestión de las versiones de dependencias relacionadas con Quarkus, garantizando consistencia en el proyecto.\n\nDependencia:\nGroup ID: ${quarkus.platform.group-id} (Definido como io.quarkus.platform).\nArtifact ID: ${quarkus.platform.artifact-id} (Definido como quarkus-bom).\nVersion: ${quarkus.platform.version} (Definido como 3.16.2).\nTipo: pom (se utiliza como BOM - Bill of Materials).\nScope: import.\n2. Dependencias del Proyecto\n   2.1. Framework Core y Validaciones\n   quarkus-hibernate-validator\n\nPropósito: Proporciona validación de datos en el modelo usando Hibernate Validator (Bean Validation 2.0).\nUso: Validaciones como @NotNull, @Size, entre otras.\nquarkus-arc\n\nPropósito: Proporciona soporte para la inyección de dependencias (CDI - Context and Dependency Injection) en Quarkus.\nUso: Gestión de Beans e inyección de dependencias con @Inject.\n2.2. Persistencia y Acceso a Datos\nquarkus-hibernate-orm-panache\n\nPropósito: Simplifica el uso de Hibernate ORM en Quarkus mediante el patrón Active Record y clases base de Panache.\nUso: Gestión de entidades JPA y queries.\nquarkus-jdbc-postgresql\n\nPropósito: Incluye el conector JDBC para PostgreSQL.\nUso: Permite la conexión a bases de datos PostgreSQL.\n2.3. API REST y Serialización\nquarkus-rest-jackson\n\nPropósito: Serializa y deserializa objetos JSON en las APIs REST utilizando Jackson.\nUso: Comunicación de APIs REST con formato JSON.\nquarkus-rest-client\n\nPropósito: Implementa clientes REST para consumir servicios externos.\nUso: Crear clientes REST basados en interfaces para microservicios.\nquarkus-rest-client-jackson\n\nPropósito: Soporte de Jackson en clientes REST.\nUso: Serialización y deserialización automática en los clientes REST.\n2.4. Seguridad\nquarkus-oidc\n\nPropósito: Proporciona autenticación basada en OpenID Connect (OIDC).\nUso: Implementación de seguridad en APIs con autenticación externa (OAuth2).\nquarkus-smallrye-jwt\n\nPropósito: Valida y procesa tokens JWT (JSON Web Token) en aplicaciones Quarkus.\nUso: Seguridad en endpoints protegidos por tokens.\n2.5. Generación de Documentación\nquarkus-smallrye-openapi\nPropósito: Genera documentación de APIs REST en formato OpenAPI (Swagger).\nUso: Exposición de una interfaz web para consultar los endpoints y probar las APIs.\n2.6. Soporte para Pruebas\nquarkus-junit5\n\nPropósito: Proporciona soporte para pruebas unitarias e integradas con JUnit 5.\nScope: test.\nUso: Escribir y ejecutar pruebas para el proyecto.\nsurefire-plugin (Definido en properties como versión 3.5.0).\n\nPropósito: Gestiona la ejecución de pruebas unitarias durante la fase de test.\n2.7. Mapas y Conversiones\nmapstruct\n\nPropósito: Framework para mapear objetos (DTOs y entidades) de manera automática mediante anotaciones.\nVersión: 1.5.2.Final.\nUso: Facilita la conversión entre modelos y DTOs.\nmapstruct-processor\n\nPropósito: Complementa a mapstruct generando el código necesario para realizar el mapeo.\nScope: provided.\nUso: Incluido para la generación de código en tiempo de compilación.\n2.8. Utilidades\nlombok\nPropósito: Simplifica el desarrollo al generar código repetitivo como getters, setters, toString, etc.\nVersión: 1.18.24.\nScope: provided.\nUso: Reducir la escritura de código boilerplate en las clases.\nResumen\nEste proyecto utiliza dependencias relacionadas con Quarkus para el desarrollo rápido de aplicaciones Java modernas, enfocándose en:\n\nPersistencia: Hibernate ORM con Panache y PostgreSQL.\nAPIs REST: Jackson, clientes REST y OpenAPI.\nSeguridad: OIDC y JWT.\nPruebas: JUnit 5.\nUtilidades: Lombok y MapStruct para la simplificación del desarrollo.\n```\n## Arquitectura Hexagonal - Documentación de la Estructura del Proyecto\nLa arquitectura hexagonal, también conocida como \"Arquitectura de Puertos y Adaptadores\", organiza el proyecto en capas bien definidas. Cada capa tiene responsabilidades específicas, con el objetivo de mantener el núcleo del dominio desacoplado de la infraestructura y otros detalles técnicos. La estructura que se muestra refleja una implementación de esta arquitectura en el contexto de un sistema de gestión escolar.\n```sql script\nEstructura del Proyecto\nLa estructura de carpetas sigue un enfoque modular y limpio, alineado con los principios de la arquitectura hexagonal:\n\n1. application\nPropósito: Contiene los casos de uso y la lógica de aplicación. Esta capa interactúa con el dominio para ejecutar operaciones específicas.\nResponsabilidades:\nImplementar los casos de uso del sistema.\nGestionar la lógica relacionada con las operaciones de negocio a nivel de aplicación.\nActuar como intermediario entre la capa de dominio y las interfaces externas.\nEjemplo de Contenido:\nServicios de aplicación (e.g., StudentService, CourseService).\nImplementaciones de interfaces de puertos definidos en el dominio.\n2. config\nPropósito: Gestiona la configuración del proyecto, como beans de Quarkus, configuración de seguridad, y otros aspectos técnicos.\nResponsabilidades:\nConfigurar dependencias externas (e.g., bases de datos, seguridad, integración con APIs externas).\nGestionar configuraciones específicas del framework (Quarkus en este caso).\nEjemplo de Contenido:\nConfiguración de OIDC, JWT o propiedades del entorno.\nClases como DatabaseConfig o SecurityConfig.\n3. domain\nPropósito: Representa el núcleo del sistema. Contiene los modelos del dominio y las interfaces (puertos) que definen las reglas del negocio.\nResponsabilidades:\nDefinir entidades de dominio (e.g., Student, Course, Teacher).\nIncluir interfaces (puertos) que los adaptadores deben implementar.\nImplementar la lógica de negocio pura, sin dependencias externas.\nEjemplo de Contenido:\nEntidades JPA o Panache (e.g., StudentEntity, CourseEntity).\nInterfaces de puertos (e.g., StudentRepository, CourseRepository).\nServicios de dominio con lógica independiente de la infraestructura.\n4. infrastructure\nPropósito: Proporciona implementaciones de los adaptadores necesarios para interactuar con sistemas externos, como bases de datos o servicios REST.\nResponsabilidades:\nImplementar los adaptadores secundarios (e.g., repositorios de datos, clientes REST).\nGestionar la interacción con detalles técnicos (e.g., acceso a la base de datos o integración con APIs externas).\nEjemplo de Contenido:\nImplementaciones de repositorios (e.g., StudentRepositoryImpl).\nClientes REST o conectores externos (e.g., ExternalApiClient).\nConfiguración de conectores de base de datos o mensajería.\n5. resource\nPropósito: Contiene los controladores o endpoints expuestos para interactuar con el sistema.\nResponsabilidades:\nImplementar los adaptadores primarios, es decir, interfaces de entrada al sistema (como APIs REST).\nRecibir solicitudes de usuarios o sistemas externos y delegarlas a los casos de uso de la capa application.\nEjemplo de Contenido:\nControladores REST (e.g., StudentController, CourseController).\nEndpoints que exponen funcionalidades a través de HTTP.\n6. resources\nPropósito: Almacena los archivos de configuración y recursos estáticos del proyecto.\nResponsabilidades:\nGestionar configuraciones específicas del entorno o del framework.\nIncluir configuraciones de propiedades, scripts SQL o plantillas estáticas.\nEjemplo de Contenido:\nArchivo application.properties: Contiene las configuraciones principales (base de datos, Quarkus, JWT, etc.).\nRelación entre las Capas\nCore del Sistema (domain):\n\nDefine las reglas de negocio y las interfaces (puertos).\nTotalmente independiente de las demás capas.\nCapa de Aplicación (application):\n\nInteractúa directamente con el dominio.\nImplementa la lógica para casos de uso específicos.\nAdaptadores:\n\nPrimarios (resource): Manejan la interacción con el usuario o sistemas externos (por ejemplo, APIs REST).\nSecundarios (infrastructure): Proveen implementaciones concretas para los puertos definidos en el dominio (repositorios, clientes REST, etc.).\nConfiguración (config):\n\nGestiona dependencias y configuraciones externas necesarias para el funcionamiento del sistema.\nBeneficios de Esta Estructura\nDesacoplamiento:\nLa lógica del negocio está aislada en el dominio, independiente de los detalles de la infraestructura.\nFlexibilidad:\nCambiar un adaptador (e.g., de PostgreSQL a MongoDB) no afecta al núcleo del dominio.\nTestabilidad:\nLas reglas de negocio pueden ser probadas sin depender de las implementaciones de infraestructura.\nEscalabilidad:\nLa modularidad permite añadir o modificar funcionalidades sin afectar otras partes del sistema.\n```\n![architect-hexagonal.png](architect-hexagonal.png)\n\n## Integración de Keycloak para la Autenticación\nKeycloak es un sistema de gestión de identidad y acceso (IAM) de código abierto. Proporciona autenticación y autorización listas para usar, soportando estándares como OpenID Connect (OIDC), OAuth2 y SAML. En este sistema, Keycloak se utiliza para manejar la autenticación de usuarios y proteger los recursos expuestos por las APIs REST.\n## Objetivo\nProporcionar autenticación segura a través de OpenID Connect (OIDC).\nProteger los endpoints de la API REST utilizando JSON Web Tokens (JWT) generados por Keycloak.\nFacilitar la gestión centralizada de usuarios, roles y permisos.\n![keycloak.png](keycloak.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhuancho%2Fschool-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhuancho%2Fschool-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhuancho%2Fschool-api/lists"}