# yyoshda/pi_1_semestre architecture

> Architecture diagram of the GitHub repository yyoshda/pi_1_semestre, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yyoshda/pi_1_semestre
- Repository: https://github.com/yyoshda/pi_1_semestre

## Overview

1. **System type and runtime**
   - This is a **Java desktop application** built with **Maven** and a **Swing-based UI**.
   - The project is a monolithic client that runs locally, boots from `br.maua.Main`, and uses `AppConfig` for application wiring/configuration.

2. **Overall purpose**
   - The app implements **“Jornada Mauá”**, a gamified academic platform for classroom activities.
   - It supports two main roles: **professor** and **aluno**.
   - The gameplay/learning model appears to revolve around **classes, tasks, questions, answers, submissions, and a board/progression layer**.

3. **Presentation layer**
   - All user interaction lives under `br.maua.presentation`.
   - The UI is organized into many Swing screens and modal dialogs such as login, cadastro, professor home, student questions, task creation, grading/correction, class management, and profile views.
   - The `.form` files show these are GUI-builder-backed screens, not a web frontend.

4. **Role-based navigation**
   - `TelaLogin`, `TelaCadastro`, and `ControladorCredenciais` form the entry path and authentication/identity flow.
   - After login, the application branches into different navigation paths for professor and aluno.
   - `TelaNavegacao` and the various “home”, “painel”, and “modal” screens indicate the app is organized around **screen-to-screen transitions** rather than a single-page flow.

5. **Core academic/game domain**
   - The `domain` package contains the business model:
     - **People and identity**: `Usuario`, `Aluno`, `Professor`
     - **Organization**: `Casa`, `Curso`, `Ano`, `Turma`, `Subturma`, `Secao`
     - **Game/progression**: `Tabuleiro`, `Tarefa`, `Tentativa`
     - **Assessment**: `Questao`, `Resposta`, and variants for different question/answer types
   - This suggests the platform models both **course structure** and **game mechanics** together.

6. **Question and response polymorphism**
   - The codebase distinguishes several task/question types:
     - `QuestaoAlternativa`, `QuestaoDissertativa`, `QuestaoUpload`
     - `RespostaAlternativa`, `RespostaDissertativa`, `RespostaUpload`
     - `Alternativa` as the choice option entity
   - The UI mirrors this split: the task creation and student question screens include dedicated components for each question format.
   - This is a key architectural boundary because task handling is type-specific throughout the app.

7. **Service layer**
   - `JornadaService` and `ArquivoService` sit between UI and persistence.
   - `JornadaService` likely orchestrates domain operations such as creating tasks, submitting responses, grading, and progress updates.
   - `ArquivoService` handles file-related behavior, which is important because the app supports upload-based tasks and stored student submissions.

8. **Persistence layer**
   - The `infrastructure.DAO` package contains one DAO per main entity or relationship.
   - Examples include `AlunoDAO`, `ProfessorDAO`, `QuestaoDAO`, `RespostaDAO`, `TurmaDAO`, `TarefaDAO`, `TentativaDAO`, and specialized DAOs for each question/answer subtype.
   - `ConnectionFactory` centralizes database connections, and `jornadamauadbmodel.sql` provides the database schema/model.
   - This is a classic **DAO + relational database** architecture, with the domain model mapped manually rather than through a heavy ORM layer.

9. **File storage and uploads**
   - The repository includes both `data/uploads/...` and `src/main/resources/...` with student and professor files.
   - This indicates the application persists uploaded artifacts on the **local filesystem**, not only in the database.
   - The presence of `assets/baixados` and upload directories suggests two file flows: stored submission files and downloadable/template assets.

10. **Corretions and submission lifecycle**
   - There are explicit screens for student submission and professor review:
     - `TelaQuestionarioAluno`, `TelaUploadAluno`, `TelaTarefaAluno`
     - `TelaCorrecaoTarefa`, `TelaNotaAluno`, `TelasNotasProfessor`
   - This points to a lifecycle where professors create tasks, students respond through different formats, and professors later correct or score submissions.
   - `Tentativa` likely represents repeated attempts or submission instances.

11. **Class management and roster operations**
   - The app includes multiple screens for managing institutional structure:
     - creating classes and sections, adding students, viewing students in a class, and class dashboards.
   - `TurmaSubturmaDAO` suggests many-to-many or association logic between class groupings.
   - This is the administrative backbone that ties users to tasks and game progression.

12. **Board/game mechanics**
   - `Tabuleiro` and the dedicated board screen (`TelaTabuleiro`) imply a game board or progress map is part of the experience.
   - `Casa` is likely a board tile or position concept used to represent advancement.
   - Combined with tasks and attempts, the architecture supports a gamified loop: **participate → answer → score → advance on board**.

13. **UI composition and reusable widgets**
   - Several screens have internal `Components` packages, such as quest panels and buttons.
   - These reusable Swing components are used to render different task/question types and class/action rows consistently.
   - That separation keeps the larger screens from owning all rendering logic directly.

14. **Repository and build tooling**
   - The project is built with **Maven** (`pom.xml`) and has NetBeans metadata (`nbactions.xml`).
   - `target/` contains compiled outputs, confirming a standard Java build pipeline.
   - `.env.example` suggests some configuration values may be externalized, even though the main architecture is still local desktop + DB + filesystem.

15. **Key architectural boundaries to diagram**
   - **UI boundary**: screens/forms in `presentation`
   - **Application logic boundary**: `service` and credential control
   - **Domain boundary**: entities and enums in `domain` / `enums`
   - **Persistence boundary**: DAOs + `ConnectionFactory`
   - **File boundary**: upload/download storage under `data/uploads` and resources/assets
   - The most important data flow is: **user action in Swing UI → service/controller logic → DAO/database and file storage → updated screen state**.

Main entry points: [`src/main/java/br/maua/infrastructure/DAO/AlunoDAO.java`](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/infrastructure/DAO/AlunoDAO.java) (DAOs), [`src/main/java/br/maua/service/JornadaService.java`](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/service/JornadaService.java) (JornadaService), [`src/main/java/br/maua/presentation/TelaTarefasAluno/TelaTarefaAluno.java`](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaTarefasAluno/TelaTarefaAluno.java) (Aluno Home), [`src/main/java/br/maua/presentation/TelaNavegacao.java`](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaNavegacao.java) (Navegação)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_main(("Main<br/>entrypoint<br/>[Main.java]"))
  node_appconfig["AppConfig<br/>wiring<br/>[AppConfig.java]"]
end

subgraph group_presentation["Presentation"]
  node_login["Login<br/>screen<br/>[TelaLogin.java]"]
  node_cadastro["Cadastro<br/>screen<br/>[TelaCadastro.java]"]
  node_nav["Navegação<br/>screen-router<br/>[TelaNavegacao.java]"]
  node_profhome["Home Prof<br/>screen"]
  node_alunohome["Aluno Home<br/>screen"]
  node_criartarefa["Criar Tarefa<br/>screen"]
  node_questionario["Questionário<br/>screen"]
  node_uploadaluno["Upload Aluno<br/>screen"]
  node_correcao["Correção<br/>screen"]
  node_tabuleiroui["Tabuleiro<br/>screen"]
end

subgraph group_domain["Domain"]
  node_usuario(("Usuário<br/>entity<br/>[Usuario.java]"))
  node_estrutura["Turma/Curso<br/>entity-set<br/>[Turma.java]"]
  node_questao{{"Questões<br/>polymorphic-entity<br/>[Questao.java]"}}
  node_resposta{{"Respostas<br/>polymorphic-entity<br/>[Resposta.java]"}}
  node_tarefa["Tarefa<br/>entity<br/>[Tarefa.java]"]
  node_tabuleiro["Tabuleiro<br/>game-entity<br/>[Tabuleiro.java]"]
end

subgraph group_application["Application"]
  node_jornada["JornadaService"]
  node_arquivo["ArquivoService"]
  node_credenciais["Credenciais<br/>controller"]
end

subgraph group_persistence["Persistence"]
  node_connection[("ConnectionFactory<br/>db-connection")]
  node_daos["DAOs<br/>repository-layer<br/>[AlunoDAO.java]"]
  node_dbschema["SQL Model<br/>schema"]
end

subgraph group_storage["Storage"]
  node_uploads["Uploads<br/>filesystem"]
  node_assets["Assets<br/>resources"]
end

node_main -->|"boots"| node_appconfig
node_appconfig -->|"opens"| node_login
node_login -->|"authenticates"| node_credenciais
node_cadastro -->|"registers"| node_credenciais
node_credenciais -->|"routes"| node_nav
node_nav -->|"professor"| node_profhome
node_nav -->|"aluno"| node_alunohome
node_profhome -->|"creates"| node_criartarefa
node_profhome -->|"reviews"| node_correcao
node_alunohome -->|"answers"| node_questionario
node_alunohome -->|"uploads"| node_uploadaluno
node_alunohome -->|"progresses"| node_tabuleiroui
node_criartarefa -->|"uses"| node_jornada
node_questionario -->|"submits"| node_jornada
node_uploadaluno -->|"stores"| node_arquivo
node_correcao -->|"grades"| node_jornada
node_jornada -->|"persists"| node_daos
node_jornada -->|"moves files"| node_arquivo
node_daos -->|"connects"| node_connection
node_connection -.->|"targets"| node_dbschema
node_arquivo -->|"reads/writes"| node_uploads
node_criartarefa -->|"composes"| node_questao
node_questionario -->|"produces"| node_resposta
node_tabuleiroui -->|"renders"| node_tabuleiro
node_jornada -->|"orchestrates"| node_tarefa
node_jornada -->|"updates"| node_tabuleiro
node_daos -->|"stores"| node_usuario
node_daos -->|"stores"| node_estrutura
node_daos -->|"stores"| node_questao
node_daos -->|"stores"| node_resposta
node_daos -->|"stores"| node_tarefa
node_assets -.->|"templates"| node_uploadaluno

click node_main "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/Main.java"
click node_appconfig "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/config/AppConfig.java"
click node_login "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaLogin/TelaLogin.java"
click node_cadastro "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaCadastro/TelaCadastro.java"
click node_nav "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaNavegacao.java"
click node_profhome "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaHomeProfessor/TelaPainelAdministrativo.java"
click node_alunohome "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaTarefasAluno/TelaTarefaAluno.java"
click node_criartarefa "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaCriarTarefa/TelaCriarTarefa.java"
click node_questionario "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaQuestionarioAluno/TelaQuestionarioAluno.java"
click node_uploadaluno "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaUploadAluno/TelaUploadAluno.java"
click node_correcao "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaCorrecaoTarefa/TelaCorrecaoTarefa.java"
click node_tabuleiroui "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaTabuleiro/TelaTabuleiro1.java"
click node_usuario "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Usuario.java"
click node_estrutura "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Turma.java"
click node_questao "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Questao.java"
click node_resposta "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Resposta.java"
click node_tarefa "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Tarefa.java"
click node_tabuleiro "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Tabuleiro.java"
click node_jornada "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/service/JornadaService.java"
click node_arquivo "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/service/ArquivoService.java"
click node_credenciais "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/controller/ControladorCredenciais.java"
click node_connection "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/infrastructure/ConnectionFactory.java"
click node_daos "https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/infrastructure/DAO/AlunoDAO.java"
click node_dbschema "https://github.com/yyoshda/pi_1_semestre/blob/master/jornadamauadbmodel.sql"
click node_uploads "https://github.com/yyoshda/pi_1_semestre/tree/master/data/uploads"
click node_assets "https://github.com/yyoshda/pi_1_semestre/tree/master/src/main/resources/assets"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_appconfig toneBlue
class node_login,node_cadastro,node_nav,node_profhome,node_alunohome,node_criartarefa,node_questionario,node_uploadaluno,node_correcao,node_tabuleiroui toneAmber
class node_usuario,node_estrutura,node_questao,node_resposta,node_tarefa,node_tabuleiro toneMint
class node_jornada,node_arquivo,node_credenciais toneRose
class node_connection,node_daos,node_dbschema toneIndigo
class node_uploads,node_assets toneTeal
```

## Components

### Bootstrap

Application entrypoint and wiring

- [Main](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/Main.java): entrypoint · Bootstraps the desktop app · `src/main/java/br/maua/Main.java`
- [AppConfig](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/config/AppConfig.java): wiring · Application configuration and dependency setup · `src/main/java/br/maua/config/AppConfig.java`

### Presentation

Swing screens and reusable UI components

- [Login](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaLogin/TelaLogin.java): screen · Entry screen for authentication · `src/main/java/br/maua/presentation/TelaLogin/TelaLogin.java`
- [Cadastro](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaCadastro/TelaCadastro.java): screen · User registration screen · `src/main/java/br/maua/presentation/TelaCadastro/TelaCadastro.java`
- [Navegação](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaNavegacao.java): screen-router · Role-based screen navigation · `src/main/java/br/maua/presentation/TelaNavegacao.java`
- [Home Prof](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaHomeProfessor/TelaPainelAdministrativo.java): screen · Professor landing and admin panel · `src/main/java/br/maua/presentation/TelaHomeProfessor/TelaPainelAdministrativo.java`
- [Aluno Home](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaTarefasAluno/TelaTarefaAluno.java): screen · Student task and progress entry point · `src/main/java/br/maua/presentation/TelaTarefasAluno/TelaTarefaAluno.java`
- [Criar Tarefa](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaCriarTarefa/TelaCriarTarefa.java): screen · Task authoring workflow · `src/main/java/br/maua/presentation/TelaCriarTarefa/TelaCriarTarefa.java`
- [Questionário](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaQuestionarioAluno/TelaQuestionarioAluno.java): screen · Student task answering screen · `src/main/java/br/maua/presentation/TelaQuestionarioAluno/TelaQuestionarioAluno.java`
- [Upload Aluno](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaUploadAluno/TelaUploadAluno.java): screen · File submission screen · `src/main/java/br/maua/presentation/TelaUploadAluno/TelaUploadAluno.java`
- [Correção](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaCorrecaoTarefa/TelaCorrecaoTarefa.java): screen · Teacher correction workflow · `src/main/java/br/maua/presentation/TelaCorrecaoTarefa/TelaCorrecaoTarefa.java`
- [Tabuleiro](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/presentation/TelaTabuleiro/TelaTabuleiro1.java): screen · Game board/progression view · `src/main/java/br/maua/presentation/TelaTabuleiro/TelaTabuleiro1.java`

### Domain

Core academic and game model

- [Usuário](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Usuario.java): entity · Base person and identity model · `src/main/java/br/maua/domain/Usuario.java`
- [Turma/Curso](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Turma.java): entity-set · Academic organization and roster model · `src/main/java/br/maua/domain/Turma.java`
- [Questões](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Questao.java): polymorphic-entity · Question types and alternatives · `src/main/java/br/maua/domain/Questao.java`
- [Respostas](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Resposta.java): polymorphic-entity · Student answer types · `src/main/java/br/maua/domain/Resposta.java`
- [Tarefa](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Tarefa.java): entity · Assignment and attempt lifecycle · `src/main/java/br/maua/domain/Tarefa.java`
- [Tabuleiro](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/domain/Tabuleiro.java): game-entity · Board and progress mechanics · `src/main/java/br/maua/domain/Tabuleiro.java`

### Application

Services and orchestration

- [JornadaService](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/service/JornadaService.java): service · Coordinates tasks, submissions and progression · `src/main/java/br/maua/service/JornadaService.java`
- [ArquivoService](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/service/ArquivoService.java): service · Handles upload and file lifecycle · `src/main/java/br/maua/service/ArquivoService.java`
- [Credenciais](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/controller/ControladorCredenciais.java): controller · Authentication and credential flow · `src/main/java/br/maua/controller/ControladorCredenciais.java`

### Persistence

Database access and connection handling

- [ConnectionFactory](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/infrastructure/ConnectionFactory.java): db-connection · Creates database connections · `src/main/java/br/maua/infrastructure/ConnectionFactory.java`
- [DAOs](https://github.com/yyoshda/pi_1_semestre/blob/master/src/main/java/br/maua/infrastructure/DAO/AlunoDAO.java): repository-layer · Entity-specific DAO layer · `src/main/java/br/maua/infrastructure/DAO/AlunoDAO.java`
- [SQL Model](https://github.com/yyoshda/pi_1_semestre/blob/master/jornadamauadbmodel.sql): schema · Relational schema definition · `jornadamauadbmodel.sql`

### Storage

Local file and resource assets

- [Uploads](https://github.com/yyoshda/pi_1_semestre/tree/master/data/uploads): filesystem · Stored student and professor files · `data/uploads`
- [Assets](https://github.com/yyoshda/pi_1_semestre/tree/master/src/main/resources/assets): resources · Bundled downloadable resources · `src/main/resources/assets`

## Connections

- Main → AppConfig: boots · Main starts the application wiring
- AppConfig → Login: opens · Configuration leads to the initial screen
- Login → Credenciais: authenticates · Login delegates identity checks
- Cadastro → Credenciais: registers · Registration uses the credential flow
- Credenciais → Navegação: routes · Authentication selects the next screen by role
- Navegação → Home Prof: professor · Professor path opens admin/home screens
- Navegação → Aluno Home: aluno · Student path opens task screens
- Home Prof → Criar Tarefa: creates · Professor builds new tasks
- Home Prof → Correção: reviews · Professor corrects submissions
- Aluno Home → Questionário: answers · Student works on question-based tasks
- Aluno Home → Upload Aluno: uploads · Student submits file-based work
- Aluno Home → Tabuleiro: progresses · Student views board progression
- Criar Tarefa → JornadaService: uses · Task creation is coordinated by service logic
- Questionário → JornadaService: submits · Answers are handed to the application service
- Upload Aluno → ArquivoService: stores · Uploaded files are managed by file service
- Correção → JornadaService: grades · Corrections update attempts and scores
- JornadaService → DAOs: persists · Service layer writes and reads domain data
- JornadaService → ArquivoService: moves files · Service coordinates file-backed submissions
- DAOs → ConnectionFactory: connects · DAOs obtain database connections
- ConnectionFactory → SQL Model: targets · Connection layer serves the relational schema
- ArquivoService → Uploads: reads/writes · File service stores submission artifacts locally
- Criar Tarefa → Questões: composes · Task authoring builds polymorphic questions
- Questionário → Respostas: produces · Student interaction creates answers
- Tabuleiro → Tabuleiro: renders · Board screen reflects game progress model
- JornadaService → Tarefa: orchestrates · Service manages assignment lifecycle
- JornadaService → Tabuleiro: updates · Progress changes affect the board state
- DAOs → Usuário: stores · DAO layer persists users and roles
- DAOs → Turma/Curso: stores · DAO layer persists class and course structure
- DAOs → Questões: stores · DAO layer persists question variants
- DAOs → Respostas: stores · DAO layer persists answer variants
- DAOs → Tarefa: stores · DAO layer persists tasks and attempts
- Assets → Upload Aluno: templates · Bundled assets support downloadable task files