# higor-castro/studyflow-backend architecture

> Architecture diagram of the GitHub repository higor-castro/studyflow-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/higor-castro/studyflow-backend
- Repository: https://github.com/higor-castro/studyflow-backend
- Video tour (about a minute): https://gitdiagram.com/higor-castro/studyflow-backend/video

## Overview

StudyFlow is a Spring REST backend. The sampled implementation centers on account registration and login: credentials are checked, consent and temporary lockouts are considered, a second-factor code is emailed, and a JWT is issued after code validation. It also supports password recovery and personal-data/consent operations. The README describes a broader study planner, but no subject, task, exam, or deadline modules appear in the supplied tree, so those capabilities are not mapped as implemented. Some controller and service excerpts are partial; links for unsampled features are limited to documented or tree-supported evidence.

Main entry points: [`src/main/java/com/edu/StudyFlow/controller/UserController.java`](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/controller/UserController.java) (User endpoints), [`src/main/java/com/edu/StudyFlow/service/RedefinirSenhaService.java`](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/RedefinirSenhaService.java) (Password recovery), [`src/main/java/com/edu/StudyFlow/service/LogService.java`](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/LogService.java) (Activity logging), [`src/main/java/com/edu/StudyFlow/service/UserService.java`](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/UserService.java) (Account service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST API"]
  node_usercontroller["User endpoints"]
  node_admincontroller["Admin endpoint"]
  node_exceptionhandler["Error responses"]
  node_validation["Request validation"]
end

subgraph group_identity["Identity and security"]
  node_userservice["Account service<br/>[UserService.java]"]
  node_loginservice["Login throttling"]
  node_twofaservice["Two-factor codes<br/>[TwoFAService.java]"]
  node_recoveryservice["Password recovery"]
  node_jwtservice["JWT lifecycle<br/>[JwtService.java]"]
  node_jwtfilter["JWT request filter<br/>[JwtAuthFilter.java]"]
  node_userdetails["User lookup"]
  node_securityconfig["Security configuration"]
  node_emailservice["Email delivery<br/>[EmailService.java]"]
end

subgraph group_privacy["Consent and privacy"]
  node_consentservice["Consent management"]
  node_logservice["Activity logging<br/>[LogService.java]"]
end

subgraph group_persistence["Persistence and records"]
  node_userrepo["User records"]
  node_consentrepo["Consent records"]
  node_tokenrepo["Revoked tokens"]
  node_logrepo["Audit records<br/>[LogRepository.java]"]
end

node_student(("Client"))
node_brevo["Brevo email"]
node_database[("PostgreSQL")]

node_student -->|"sends requests"| node_usercontroller
node_usercontroller -->|"handles accounts"| node_userservice
node_usercontroller -->|"checks lockout"| node_loginservice
node_usercontroller -->|"requests code"| node_twofaservice
node_usercontroller -->|"issues token"| node_jwtservice
node_usercontroller -->|"handles recovery"| node_recoveryservice
node_usercontroller -->|"manages consent"| node_consentservice
node_usercontroller -->|"records actions"| node_logservice
node_usercontroller -->|"accepts validated input"| node_validation
node_usercontroller -->|"raises handled errors"| node_exceptionhandler
node_admincontroller -->|"returns response"| node_student
node_userservice -->|"reads and writes"| node_userrepo
node_userservice -->|"registers or reads consent"| node_consentservice
node_loginservice -->|"records lockout events"| node_logservice
node_twofaservice -->|"sends code"| node_emailservice
node_recoveryservice -->|"looks up account"| node_userrepo
node_recoveryservice -->|"resets password"| node_userservice
node_recoveryservice -->|"sends recovery code"| node_emailservice
node_recoveryservice -->|"records recovery events"| node_logservice
node_emailservice -.->|"delivers messages"| node_brevo
node_consentservice -->|"reads and writes"| node_consentrepo
node_consentservice -->|"records consent events"| node_logservice
node_jwtfilter -->|"checks token"| node_jwtservice
node_jwtfilter -->|"loads identity"| node_userdetails
node_userdetails -->|"finds user"| node_userrepo
node_jwtservice -->|"stores revoked token"| node_tokenrepo
node_userrepo -->|"persists users"| node_database
node_consentrepo -->|"persists consent"| node_database
node_tokenrepo -->|"persists revocations"| node_database
node_logservice -->|"persists logs"| node_logrepo
node_logrepo -->|"persists records"| node_database

click node_usercontroller "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/controller/UserController.java"
click node_admincontroller "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/controller/UserAdminController.java"
click node_exceptionhandler "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/exception/GlobalExceptionHandler.java"
click node_validation "https://github.com/higor-castro/studyflow-backend/tree/main/src/main/java/com/edu/StudyFlow/validation"
click node_userservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/UserService.java"
click node_loginservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/LoginTimeService.java"
click node_twofaservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/TwoFAService.java"
click node_recoveryservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/RedefinirSenhaService.java"
click node_jwtservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/JwtService.java"
click node_jwtfilter "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/JwtAuthFilter.java"
click node_userdetails "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/CustomUserDetailsService.java"
click node_securityconfig "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/SecurityConfig.java"
click node_consentservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/ConsentimentoService.java"
click node_logservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/LogService.java"
click node_emailservice "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/EmailService.java"
click node_userrepo "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/UserRepository.java"
click node_consentrepo "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/ConsentimentoRepository.java"
click node_tokenrepo "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/TokenInvalidadoRepository.java"
click node_logrepo "https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/LogRepository.java"

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_usercontroller,node_admincontroller,node_exceptionhandler,node_validation,node_student toneBlue
class node_userservice,node_loginservice,node_twofaservice,node_recoveryservice,node_jwtservice,node_jwtfilter,node_userdetails,node_securityconfig,node_emailservice,node_database toneAmber
class node_consentservice,node_logservice toneMint
class node_userrepo,node_consentrepo,node_tokenrepo,node_logrepo toneRose
class node_brevo toneIndigo
```

## Components

### REST API

- [User endpoints](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/controller/UserController.java): `src/main/java/com/edu/StudyFlow/controller/UserController.java`
- [Admin endpoint](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/controller/UserAdminController.java): `src/main/java/com/edu/StudyFlow/controller/UserAdminController.java`
- [Error responses](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/exception/GlobalExceptionHandler.java): `src/main/java/com/edu/StudyFlow/exception/GlobalExceptionHandler.java`
- [Request validation](https://github.com/higor-castro/studyflow-backend/tree/main/src/main/java/com/edu/StudyFlow/validation): `src/main/java/com/edu/StudyFlow/validation`

### Identity and security

- [Account service](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/UserService.java): `src/main/java/com/edu/StudyFlow/service/UserService.java`
- [Login throttling](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/LoginTimeService.java): `src/main/java/com/edu/StudyFlow/service/LoginTimeService.java`
- [Two-factor codes](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/TwoFAService.java): `src/main/java/com/edu/StudyFlow/service/TwoFAService.java`
- [Password recovery](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/RedefinirSenhaService.java): `src/main/java/com/edu/StudyFlow/service/RedefinirSenhaService.java`
- [JWT lifecycle](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/JwtService.java): `src/main/java/com/edu/StudyFlow/security/JwtService.java`
- [JWT request filter](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/JwtAuthFilter.java): `src/main/java/com/edu/StudyFlow/security/JwtAuthFilter.java`
- [User lookup](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/CustomUserDetailsService.java): `src/main/java/com/edu/StudyFlow/security/CustomUserDetailsService.java`
- [Security configuration](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/security/SecurityConfig.java): `src/main/java/com/edu/StudyFlow/security/SecurityConfig.java`
- [Email delivery](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/EmailService.java): `src/main/java/com/edu/StudyFlow/service/EmailService.java`

### Consent and privacy

- [Consent management](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/ConsentimentoService.java): `src/main/java/com/edu/StudyFlow/service/ConsentimentoService.java`
- [Activity logging](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/service/LogService.java): `src/main/java/com/edu/StudyFlow/service/LogService.java`

### Persistence and records

- [User records](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/UserRepository.java): `src/main/java/com/edu/StudyFlow/repository/UserRepository.java`
- [Consent records](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/ConsentimentoRepository.java): `src/main/java/com/edu/StudyFlow/repository/ConsentimentoRepository.java`
- [Revoked tokens](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/TokenInvalidadoRepository.java): `src/main/java/com/edu/StudyFlow/repository/TokenInvalidadoRepository.java`
- [Audit records](https://github.com/higor-castro/studyflow-backend/blob/main/src/main/java/com/edu/StudyFlow/repository/LogRepository.java): `src/main/java/com/edu/StudyFlow/repository/LogRepository.java`

### Other components

- **Client**
- **Brevo email**
- **PostgreSQL**

## Connections

- Client → User endpoints: sends requests
- User endpoints → Account service: handles accounts
- User endpoints → Login throttling: checks lockout
- User endpoints → Two-factor codes: requests code
- User endpoints → JWT lifecycle: issues token
- User endpoints → Password recovery: handles recovery
- User endpoints → Consent management: manages consent
- User endpoints → Activity logging: records actions
- User endpoints → Request validation: accepts validated input
- User endpoints → Error responses: raises handled errors
- Admin endpoint → Client: returns response
- Account service → User records: reads and writes
- Account service → Consent management: registers or reads consent
- Login throttling → Activity logging: records lockout events
- Two-factor codes → Email delivery: sends code
- Password recovery → User records: looks up account
- Password recovery → Account service: resets password
- Password recovery → Email delivery: sends recovery code
- Password recovery → Activity logging: records recovery events
- Email delivery → Brevo email: delivers messages
- Consent management → Consent records: reads and writes
- Consent management → Activity logging: records consent events
- JWT request filter → JWT lifecycle: checks token
- JWT request filter → User lookup: loads identity
- User lookup → User records: finds user
- JWT lifecycle → Revoked tokens: stores revoked token
- User records → PostgreSQL: persists users
- Consent records → PostgreSQL: persists consent
- Revoked tokens → PostgreSQL: persists revocations
- Activity logging → Audit records: persists logs
- Audit records → PostgreSQL: persists records