# ryanmferreira/polikt-spring architecture

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

- Interactive diagram: https://gitdiagram.com/ryanmferreira/polikt-spring
- Repository: https://github.com/ryanmferreira/polikt-spring

## Overview

Polikt is a political-education and civic-awareness REST API. Clients retrieve or manage news and agencies, create users and authenticate, and build ordered courses from modules and content or guides from steps. Controllers own these requests and call their repositories; module/content and guide/step controllers also resolve their parent records. The README documents JWT-protected operations and PostgreSQL persistence. The sampled source confirms several controller-to-repository calls and JWT issuance; some documented feature wiring and request authorization details are represented only at the subsystem level.

Main entry points: [`api/src/main/java/com/polikt/api/user/UserController.java`](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/user/UserController.java) (User API), [`api/src/main/java/com/polikt/api/guide/step/GuideStepController.java`](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/step/GuideStepController.java) (Guide step API), [`api/src/main/java/com/polikt/api/course/module/ModuleController.java`](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/ModuleController.java) (Module API), [`api/src/main/java/com/polikt/api/course/module/content/ContentController.java`](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/content/ContentController.java) (Module content API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_users["User API"]
  node_userrepo["User repository"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_security["Security configuration"]
  node_jwtfilter["JWT auth filter<br/>[JwtAuthFilter.java]"]
end

subgraph group_civic["Civic content"]
  node_agencies["Agency API"]
  node_agencyrepo["Agency repository"]
  node_news["News API"]
  node_newsrepo["News repository"]
end

subgraph group_learning["Learning resources"]
  node_guides["Guide API"]
  node_guiderepo["Guide repository"]
  node_steps["Guide step API"]
  node_steprepo["Guide step repository"]
  node_courses["Course API"]
  node_courserepo["Course repository"]
  node_modules["Module API"]
  node_modulerepo["Module repository"]
  node_content["Module content API"]
  node_contentrepo["Content repository"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL")]
end

node_client(("API client"))

node_client -->|"sends requests"| node_users
node_client -->|"sends requests"| node_agencies
node_client -->|"sends requests"| node_news
node_client -->|"sends requests"| node_guides
node_client -->|"sends requests"| node_steps
node_client -->|"sends requests"| node_courses
node_client -->|"sends requests"| node_modules
node_client -->|"sends requests"| node_content
node_users -->|"reads and writes"| node_userrepo
node_users -->|"issues token"| node_jwt
node_jwtfilter -.->|"validates token"| node_jwt
node_security -.->|"configures filter"| node_jwtfilter
node_agencies -->|"reads and writes"| node_agencyrepo
node_news -->|"reads and writes"| node_newsrepo
node_guides -->|"reads and writes"| node_guiderepo
node_steps -->|"reads and writes"| node_steprepo
node_steps -->|"resolves guide"| node_guiderepo
node_courses -->|"reads and writes"| node_courserepo
node_modules -->|"reads and writes"| node_modulerepo
node_modules -->|"resolves course"| node_courserepo
node_content -->|"reads and writes"| node_contentrepo
node_content -->|"resolves module"| node_modulerepo
node_userrepo -->|"persists records"| node_postgres
node_agencyrepo -->|"persists records"| node_postgres
node_newsrepo -->|"persists records"| node_postgres
node_guiderepo -->|"persists records"| node_postgres
node_steprepo -->|"persists records"| node_postgres
node_courserepo -->|"persists records"| node_postgres
node_modulerepo -->|"persists records"| node_postgres
node_contentrepo -->|"persists records"| node_postgres

click node_users "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/user/UserController.java"
click node_userrepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/user/UserRepository.java"
click node_jwt "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/config/JwtService.java"
click node_security "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/config/SecurityConfig.java"
click node_jwtfilter "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/config/JwtAuthFilter.java"
click node_agencies "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/agency/AgencyController.java"
click node_agencyrepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/agency/AgencyRepository.java"
click node_news "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/news/NewsController.java"
click node_newsrepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/news/NewsRepository.java"
click node_guides "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/GuideController.java"
click node_guiderepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/GuideRepository.java"
click node_steps "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/step/GuideStepController.java"
click node_steprepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/step/GuideStepRepository.java"
click node_courses "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/CourseController.java"
click node_courserepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/CourseRepository.java"
click node_modules "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/ModuleController.java"
click node_modulerepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/ModuleRepository.java"
click node_content "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/content/ContentController.java"
click node_contentrepo "https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/content/ContentRepository.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_users,node_userrepo,node_jwt,node_security,node_jwtfilter,node_client toneBlue
class node_agencies,node_agencyrepo,node_news,node_newsrepo toneAmber
class node_guides,node_guiderepo,node_steps,node_steprepo,node_courses,node_courserepo,node_modules,node_modulerepo,node_content,node_contentrepo toneMint
class node_postgres toneRose
```

## Components

### Identity and access

- [User API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/user/UserController.java): `api/src/main/java/com/polikt/api/user/UserController.java`
- [User repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/user/UserRepository.java): `api/src/main/java/com/polikt/api/user/UserRepository.java`
- [JWT service](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/config/JwtService.java): `api/src/main/java/com/polikt/api/config/JwtService.java`
- [Security configuration](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/config/SecurityConfig.java): `api/src/main/java/com/polikt/api/config/SecurityConfig.java`
- [JWT auth filter](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/config/JwtAuthFilter.java): `api/src/main/java/com/polikt/api/config/JwtAuthFilter.java`

### Civic content

- [Agency API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/agency/AgencyController.java): `api/src/main/java/com/polikt/api/agency/AgencyController.java`
- [Agency repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/agency/AgencyRepository.java): `api/src/main/java/com/polikt/api/agency/AgencyRepository.java`
- [News API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/news/NewsController.java): `api/src/main/java/com/polikt/api/news/NewsController.java`
- [News repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/news/NewsRepository.java): `api/src/main/java/com/polikt/api/news/NewsRepository.java`

### Learning resources

- [Guide API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/GuideController.java): `api/src/main/java/com/polikt/api/guide/GuideController.java`
- [Guide repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/GuideRepository.java): `api/src/main/java/com/polikt/api/guide/GuideRepository.java`
- [Guide step API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/step/GuideStepController.java): `api/src/main/java/com/polikt/api/guide/step/GuideStepController.java`
- [Guide step repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/guide/step/GuideStepRepository.java): `api/src/main/java/com/polikt/api/guide/step/GuideStepRepository.java`
- [Course API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/CourseController.java): `api/src/main/java/com/polikt/api/course/CourseController.java`
- [Course repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/CourseRepository.java): `api/src/main/java/com/polikt/api/course/CourseRepository.java`
- [Module API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/ModuleController.java): `api/src/main/java/com/polikt/api/course/module/ModuleController.java`
- [Module repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/ModuleRepository.java): `api/src/main/java/com/polikt/api/course/module/ModuleRepository.java`
- [Module content API](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/content/ContentController.java): `api/src/main/java/com/polikt/api/course/module/content/ContentController.java`
- [Content repository](https://github.com/ryanmferreira/polikt-spring/blob/main/api/src/main/java/com/polikt/api/course/module/content/ContentRepository.java): `api/src/main/java/com/polikt/api/course/module/content/ContentRepository.java`

### Persistence

- **PostgreSQL**

### Other components

- **API client**

## Connections

- API client → User API: sends requests
- API client → Agency API: sends requests
- API client → News API: sends requests
- API client → Guide API: sends requests
- API client → Guide step API: sends requests
- API client → Course API: sends requests
- API client → Module API: sends requests
- API client → Module content API: sends requests
- User API → User repository: reads and writes
- User API → JWT service: issues token
- JWT auth filter → JWT service: validates token
- Security configuration → JWT auth filter: configures filter
- Agency API → Agency repository: reads and writes
- News API → News repository: reads and writes
- Guide API → Guide repository: reads and writes
- Guide step API → Guide step repository: reads and writes
- Guide step API → Guide repository: resolves guide
- Course API → Course repository: reads and writes
- Module API → Module repository: reads and writes
- Module API → Course repository: resolves course
- Module content API → Content repository: reads and writes
- Module content API → Module repository: resolves module
- User repository → PostgreSQL: persists records
- Agency repository → PostgreSQL: persists records
- News repository → PostgreSQL: persists records
- Guide repository → PostgreSQL: persists records
- Guide step repository → PostgreSQL: persists records
- Course repository → PostgreSQL: persists records
- Module repository → PostgreSQL: persists records
- Content repository → PostgreSQL: persists records