# kobevlm/pamana architecture

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

- Interactive diagram: https://gitdiagram.com/kobevlm/pamana
- Repository: https://github.com/kobevlm/pamana

## Overview

PAMANA is a gamified Filipino-learning web app: learners follow the Pamana Trail through syllable, vocabulary, and sentence activities, while parents review progress and reports. The graph combines README-described product capabilities with backend relationships visible in the supplied source index and excerpts. Frontend-to-backend request wiring and several controllers were not sampled, so those connections are shown only where the README supports the capability, not as detailed call chains.

Main entry points: [`backend/src/main/java/com/pamana/progress/ModuleLockService.java`](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ModuleLockService.java) (Module progression), [`backend/src/main/java/com/pamana/progress/ModuleProgress.java`](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ModuleProgress.java) (Module progress), [`frontend/src/pages/trail/TrailMapPage.tsx`](https://github.com/kobevlm/pamana/blob/main/frontend/src/pages/trail/TrailMapPage.tsx) (Pamana Trail), [`frontend/src/pages/modules`](https://github.com/kobevlm/pamana/tree/main/frontend/src/pages/modules) (Module activities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learner["Learner experience"]
  node_trail["Pamana Trail<br/>[TrailMapPage.tsx]"]
  node_module_pages["Module activities"]
  node_practice_pages["Practice games"]
  node_audio["Game audio<br/>[AudioContext.tsx]"]
end

subgraph group_identity["Identity and access"]
  node_auth_ui["Sign-in screens"]
  node_auth_service["Account service<br/>[AuthService.java]"]
  node_jwt["JWT security"]
end

subgraph group_learning["Learning services"]
  node_syllables["Syllable learning"]
  node_vocabulary["Vocabulary learning"]
  node_sentences["Sentence learning"]
  node_module_locks["Module progression"]
  node_module_state[("Module progress")]
end

subgraph group_insight["Parent insights"]
  node_progress["Progress analytics"]
  node_reports["PDF reports<br/>[ReportService.java]"]
  node_sessions["Session tracking"]
end

node_learner_actor(("Learner"))
node_parent_actor(("Parent"))
node_database[("PostgreSQL")]

node_learner_actor -->|"signs in"| node_auth_ui
node_auth_ui -.->|"uses account API"| node_auth_service
node_auth_service -->|"issues tokens"| node_jwt
node_learner_actor -->|"explores trail"| node_trail
node_trail -->|"opens modules"| node_module_pages
node_module_pages -->|"starts practice"| node_practice_pages
node_practice_pages -.->|"plays audio"| node_audio
node_learner_actor -.->|"learns syllables"| node_syllables
node_learner_actor -.->|"learns vocabulary"| node_vocabulary
node_learner_actor -.->|"builds sentences"| node_sentences
node_syllables -->|"checks access"| node_module_locks
node_vocabulary -->|"unlocks next"| node_module_locks
node_sentences -->|"checks access"| node_module_locks
node_module_locks -->|"updates progress"| node_module_state
node_parent_actor -.->|"views analytics"| node_progress
node_parent_actor -.->|"requests report"| node_reports
node_parent_actor -.->|"reviews sessions"| node_sessions
node_progress -->|"reads progress"| node_module_state
node_reports -->|"validates completion"| node_module_state
node_sessions -->|"stores sessions"| node_database
node_module_state -.->|"persists state"| node_database

click node_trail "https://github.com/kobevlm/pamana/blob/main/frontend/src/pages/trail/TrailMapPage.tsx"
click node_module_pages "https://github.com/kobevlm/pamana/tree/main/frontend/src/pages/modules"
click node_practice_pages "https://github.com/kobevlm/pamana/tree/main/frontend/src/pages/mastery"
click node_audio "https://github.com/kobevlm/pamana/blob/main/frontend/src/contexts/AudioContext.tsx"
click node_auth_ui "https://github.com/kobevlm/pamana/tree/main/frontend/src/pages/auth"
click node_auth_service "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/auth/AuthService.java"
click node_jwt "https://github.com/kobevlm/pamana/tree/main/backend/src/main/java/com/pamana/security"
click node_syllables "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/syllable/SyllableService.java"
click node_vocabulary "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/vocabulary/VocabularyService.java"
click node_sentences "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/sentence/SentenceService.java"
click node_module_locks "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ModuleLockService.java"
click node_progress "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ProgressService.java"
click node_reports "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/parent/ReportService.java"
click node_sessions "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/parent/SessionLogService.java"
click node_module_state "https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ModuleProgress.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_trail,node_module_pages,node_practice_pages,node_audio toneBlue
class node_auth_ui,node_auth_service,node_jwt,node_database toneAmber
class node_syllables,node_vocabulary,node_sentences,node_module_locks,node_module_state toneMint
class node_progress,node_reports,node_sessions toneRose
class node_learner_actor,node_parent_actor toneIndigo
```

## Components

### Learner experience

- [Pamana Trail](https://github.com/kobevlm/pamana/blob/main/frontend/src/pages/trail/TrailMapPage.tsx): `frontend/src/pages/trail/TrailMapPage.tsx`
- [Module activities](https://github.com/kobevlm/pamana/tree/main/frontend/src/pages/modules): `frontend/src/pages/modules`
- [Practice games](https://github.com/kobevlm/pamana/tree/main/frontend/src/pages/mastery): `frontend/src/pages/mastery`
- [Game audio](https://github.com/kobevlm/pamana/blob/main/frontend/src/contexts/AudioContext.tsx): `frontend/src/contexts/AudioContext.tsx`

### Identity and access

- [Sign-in screens](https://github.com/kobevlm/pamana/tree/main/frontend/src/pages/auth): `frontend/src/pages/auth`
- [Account service](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/auth/AuthService.java): `backend/src/main/java/com/pamana/auth/AuthService.java`
- [JWT security](https://github.com/kobevlm/pamana/tree/main/backend/src/main/java/com/pamana/security): `backend/src/main/java/com/pamana/security`

### Learning services

- [Syllable learning](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/syllable/SyllableService.java): `backend/src/main/java/com/pamana/syllable/SyllableService.java`
- [Vocabulary learning](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/vocabulary/VocabularyService.java): `backend/src/main/java/com/pamana/vocabulary/VocabularyService.java`
- [Sentence learning](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/sentence/SentenceService.java): `backend/src/main/java/com/pamana/sentence/SentenceService.java`
- [Module progression](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ModuleLockService.java): `backend/src/main/java/com/pamana/progress/ModuleLockService.java`
- [Module progress](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ModuleProgress.java): `backend/src/main/java/com/pamana/progress/ModuleProgress.java`

### Parent insights

- [Progress analytics](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/progress/ProgressService.java): `backend/src/main/java/com/pamana/progress/ProgressService.java`
- [PDF reports](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/parent/ReportService.java): `backend/src/main/java/com/pamana/parent/ReportService.java`
- [Session tracking](https://github.com/kobevlm/pamana/blob/main/backend/src/main/java/com/pamana/parent/SessionLogService.java): `backend/src/main/java/com/pamana/parent/SessionLogService.java`

### Other components

- **Learner**
- **Parent**
- **PostgreSQL**

## Connections

- Learner → Sign-in screens: signs in
- Sign-in screens → Account service: uses account API
- Account service → JWT security: issues tokens (evidence: `backend/src/main/java/com/pamana/auth/AuthService.java`)
- Learner → Pamana Trail: explores trail
- Pamana Trail → Module activities: opens modules
- Module activities → Practice games: starts practice
- Practice games → Game audio: plays audio
- Learner → Syllable learning: learns syllables
- Learner → Vocabulary learning: learns vocabulary
- Learner → Sentence learning: builds sentences
- Syllable learning → Module progression: checks access (evidence: `backend/src/main/java/com/pamana/syllable/SyllableService.java`)
- Vocabulary learning → Module progression: unlocks next (evidence: `backend/src/main/java/com/pamana/vocabulary/VocabularyService.java`)
- Sentence learning → Module progression: checks access (evidence: `backend/src/main/java/com/pamana/sentence/SentenceService.java`)
- Module progression → Module progress: updates progress (evidence: `backend/src/main/java/com/pamana/progress/ModuleLockService.java`)
- Parent → Progress analytics: views analytics
- Parent → PDF reports: requests report
- Parent → Session tracking: reviews sessions
- Progress analytics → Module progress: reads progress (evidence: `backend/src/main/java/com/pamana/progress/ProgressService.java`)
- PDF reports → Module progress: validates completion (evidence: `backend/src/main/java/com/pamana/parent/ReportService.java`)
- Session tracking → PostgreSQL: stores sessions (evidence: `backend/src/main/java/com/pamana/parent/SessionLogService.java`)
- Module progress → PostgreSQL: persists state
