# team-ctrls/totori_be architecture

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

- Interactive diagram: https://gitdiagram.com/team-ctrls/totori_be
- Repository: https://github.com/team-ctrls/totori_be

## Overview

Totori_BE is the central API and data server for a mobile reading-learning service. Children use it for personalized story creation, reading analysis, quizzes, attendance, and badges; parents and teachers review learning reports, while parents can link child accounts. The README documents AI, storage, and OAuth integrations; the source index and excerpts confirm selected service dependencies and repository interactions. Several feature modules are represented at their exact tree directories because their source was not sampled, so their internal call paths are not asserted.

Main entry points: [`src/main/java/ctrlS/totori/TotoriApplication.java`](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/TotoriApplication.java) (Totori API), [`src/main/java/ctrlS/totori/book/service/BookService.java`](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/book/service/BookService.java) (Story service), [`src/main/java/ctrlS/totori/badge/service/BadgeService.java`](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/badge/service/BadgeService.java) (Badge service), [`src/main/java/ctrlS/totori/member/service/MemberService.java`](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/member/service/MemberService.java) (Member management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and family"]
  node_auth["Auth service<br/>[AuthService.java]"]
  node_oauth["Kakao OAuth"]
  node_jwt["JWT security"]
  node_redis[("Redis tokens")]
  node_members["Member management<br/>[MemberService.java]"]
  node_memberdb[("Member data")]
  node_connections["Parent-child links"]
end

subgraph group_stories["Stories and media"]
  node_book["Story service<br/>[BookService.java]"]
  node_bookdb[("Story records")]
  node_ai["Totori AI"]
  node_images["Image generation"]
  node_audio["Audio and TTS"]
  node_s3[("AWS S3")]
end

subgraph group_learning["Learning progress"]
  node_quiz["Quiz service<br/>[QuizService.java]"]
  node_quizdb[("Quiz records")]
  node_attendance["Attendance"]
  node_badges["Badge service<br/>[BadgeService.java]"]
  node_reports["Learning reports<br/>[ReportService.java]"]
  node_stats[("Member statistics")]
end

subgraph group_platform["API and persistence"]
  node_totori["Totori API"]
  node_responses["API responses<br/>[BaseResponse.java]"]
end

node_mobile(("iOS app"))

node_mobile -->|"calls API"| node_totori
node_totori -->|"serves login"| node_auth
node_totori -->|"serves profiles"| node_members
node_totori -->|"serves linking"| node_connections
node_totori -->|"serves stories"| node_book
node_totori -->|"serves quizzes"| node_quiz
node_totori -->|"serves attendance"| node_attendance
node_totori -->|"serves badges"| node_badges
node_totori -->|"serves reports"| node_reports
node_auth -->|"reads members"| node_memberdb
node_auth -->|"issues tokens"| node_jwt
node_auth -->|"uses token store"| node_redis
node_oauth -->|"loads accounts"| node_memberdb
node_members -->|"reads and updates"| node_memberdb
node_members -->|"queries links"| node_connections
node_members -->|"resolves tokens"| node_jwt
node_members -->|"blacklists tokens"| node_redis
node_book -->|"stores stories"| node_bookdb
node_book -->|"requests stories"| node_ai
node_book -->|"checks awards"| node_badges
node_book -.->|"generates artwork"| node_images
node_book -.->|"generates narration"| node_audio
node_images -->|"stores images"| node_s3
node_audio -->|"stores audio"| node_s3
node_quiz -->|"requests quiz analysis"| node_ai
node_quiz -.->|"stores quizzes"| node_quizdb
node_quiz -->|"checks awards"| node_badges
node_reports -.->|"uses learning stats"| node_stats
node_badges -->|"reads progress"| node_stats
node_badges -->|"loads members"| node_memberdb
node_badges -->|"gets badge images"| node_s3

click node_totori "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/TotoriApplication.java"
click node_auth "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/auth/service/AuthService.java"
click node_oauth "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/auth/service/CustomOAuth2UserService.java"
click node_jwt "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/global/security/JwtTokenProvider.java"
click node_redis "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/auth/service/AuthRedisService.java"
click node_members "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/member/service/MemberService.java"
click node_memberdb "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/member/repository/MemberRepository.java"
click node_connections "https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/connect"
click node_book "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/book/service/BookService.java"
click node_bookdb "https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/book/repository"
click node_images "https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/book/service/image"
click node_audio "https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/book/service/audio"
click node_quiz "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/quiz/service/QuizService.java"
click node_quizdb "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/quiz/repository/QuizRepository.java"
click node_attendance "https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/attendance"
click node_badges "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/badge/service/BadgeService.java"
click node_reports "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/report/service/ReportService.java"
click node_stats "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/member/repository/MemberStatRepository.java"
click node_responses "https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/global/response/dto/BaseResponse.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_auth,node_oauth,node_jwt,node_redis,node_members,node_memberdb,node_connections toneBlue
class node_book,node_bookdb,node_ai,node_images,node_audio,node_s3 toneAmber
class node_quiz,node_quizdb,node_attendance,node_badges,node_reports,node_stats toneMint
class node_totori,node_responses toneRose
class node_mobile toneIndigo
```

## Components

### Identity and family

- [Auth service](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/auth/service/AuthService.java): `src/main/java/ctrlS/totori/auth/service/AuthService.java`
- [Kakao OAuth](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/auth/service/CustomOAuth2UserService.java): `src/main/java/ctrlS/totori/auth/service/CustomOAuth2UserService.java`
- [JWT security](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/global/security/JwtTokenProvider.java): `src/main/java/ctrlS/totori/global/security/JwtTokenProvider.java`
- [Redis tokens](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/auth/service/AuthRedisService.java): `src/main/java/ctrlS/totori/auth/service/AuthRedisService.java`
- [Member management](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/member/service/MemberService.java): `src/main/java/ctrlS/totori/member/service/MemberService.java`
- [Member data](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/member/repository/MemberRepository.java): `src/main/java/ctrlS/totori/member/repository/MemberRepository.java`
- [Parent-child links](https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/connect): `src/main/java/ctrlS/totori/connect`

### Stories and media

- [Story service](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/book/service/BookService.java): `src/main/java/ctrlS/totori/book/service/BookService.java`
- [Story records](https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/book/repository): `src/main/java/ctrlS/totori/book/repository`
- **Totori AI**
- [Image generation](https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/book/service/image): `src/main/java/ctrlS/totori/book/service/image`
- [Audio and TTS](https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/book/service/audio): `src/main/java/ctrlS/totori/book/service/audio`
- **AWS S3**

### Learning progress

- [Quiz service](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/quiz/service/QuizService.java): `src/main/java/ctrlS/totori/quiz/service/QuizService.java`
- [Quiz records](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/quiz/repository/QuizRepository.java): `src/main/java/ctrlS/totori/quiz/repository/QuizRepository.java`
- [Attendance](https://github.com/team-ctrls/totori_be/tree/develop/src/main/java/ctrlS/totori/attendance): `src/main/java/ctrlS/totori/attendance`
- [Badge service](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/badge/service/BadgeService.java): `src/main/java/ctrlS/totori/badge/service/BadgeService.java`
- [Learning reports](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/report/service/ReportService.java): `src/main/java/ctrlS/totori/report/service/ReportService.java`
- [Member statistics](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/member/repository/MemberStatRepository.java): `src/main/java/ctrlS/totori/member/repository/MemberStatRepository.java`

### API and persistence

- [Totori API](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/TotoriApplication.java): `src/main/java/ctrlS/totori/TotoriApplication.java`
- [API responses](https://github.com/team-ctrls/totori_be/blob/develop/src/main/java/ctrlS/totori/global/response/dto/BaseResponse.java): `src/main/java/ctrlS/totori/global/response/dto/BaseResponse.java`

### Other components

- **iOS app**

## Connections

- iOS app → Totori API: calls API
- Totori API → Auth service: serves login
- Totori API → Member management: serves profiles
- Totori API → Parent-child links: serves linking
- Totori API → Story service: serves stories
- Totori API → Quiz service: serves quizzes
- Totori API → Attendance: serves attendance
- Totori API → Badge service: serves badges
- Totori API → Learning reports: serves reports
- Auth service → Member data: reads members (evidence: `src/main/java/ctrlS/totori/auth/service/AuthService.java`)
- Auth service → JWT security: issues tokens (evidence: `src/main/java/ctrlS/totori/auth/service/AuthService.java`)
- Auth service → Redis tokens: uses token store (evidence: `src/main/java/ctrlS/totori/auth/service/AuthService.java`)
- Kakao OAuth → Member data: loads accounts (evidence: `src/main/java/ctrlS/totori/auth/service/CustomOAuth2UserService.java`)
- Member management → Member data: reads and updates (evidence: `src/main/java/ctrlS/totori/member/service/MemberService.java`)
- Member management → Parent-child links: queries links (evidence: `src/main/java/ctrlS/totori/member/service/MemberService.java`)
- Member management → JWT security: resolves tokens (evidence: `src/main/java/ctrlS/totori/member/service/MemberService.java`)
- Member management → Redis tokens: blacklists tokens (evidence: `src/main/java/ctrlS/totori/member/service/MemberService.java`)
- Story service → Story records: stores stories (evidence: `src/main/java/ctrlS/totori/book/service/BookService.java`)
- Story service → Totori AI: requests stories (evidence: `src/main/java/ctrlS/totori/book/service/BookService.java`)
- Story service → Badge service: checks awards (evidence: `src/main/java/ctrlS/totori/book/service/BookService.java`)
- Story service → Image generation: generates artwork (evidence: `src/main/java/ctrlS/totori/book/service/BookService.java`)
- Story service → Audio and TTS: generates narration (evidence: `src/main/java/ctrlS/totori/book/service/BookService.java`)
- Image generation → AWS S3: stores images
- Audio and TTS → AWS S3: stores audio (evidence: `src/main/java/ctrlS/totori/book/service/audio/S3AudioStorageService.java`)
- Quiz service → Totori AI: requests quiz analysis
- Quiz service → Quiz records: stores quizzes (evidence: `src/main/java/ctrlS/totori/quiz/service/QuizService.java`)
- Quiz service → Badge service: checks awards (evidence: `src/main/java/ctrlS/totori/quiz/service/QuizService.java`)
- Learning reports → Member statistics: uses learning stats
- Badge service → Member statistics: reads progress (evidence: `src/main/java/ctrlS/totori/badge/service/BadgeService.java`)
- Badge service → Member data: loads members (evidence: `src/main/java/ctrlS/totori/badge/service/BadgeService.java`)
- Badge service → AWS S3: gets badge images (evidence: `src/main/java/ctrlS/totori/badge/service/BadgeService.java`)