# aditisingh-05/historia-backend architecture

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

- Interactive diagram: https://gitdiagram.com/aditisingh-05/historia-backend
- Repository: https://github.com/aditisingh-05/historia-backend

## Overview

Historia is a Spring Boot backend API for a multi-app story-reading product. The principal reader journey is account authentication, app-scoped catalogue access, entitlement checks, and reading; the backend also supports content authoring/import, purchases, ratings, annotations, support, and administration. The graph emphasizes documented capabilities and sampled service relationships. Some controller wiring and several feature implementations were not sampled, so uncertain links are omitted rather than inferred.

Main entry points: [`src/main/java/com/bitverse/historia/auth/application/AuthService.java`](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/application/AuthService.java) (Reader Auth), [`src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java`](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java) (Content Workflow), [`src/main/java/com/bitverse/historia/billing/application/BillingService.java`](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/billing/application/BillingService.java) (Purchase Verification), [`src/main/java/com/bitverse/historia/auth/api/AuthController.java`](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/api/AuthController.java) (Auth API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity &amp; Platform"]
  node_auth_api["Auth API"]
  node_auth_service["Reader Auth<br/>[AuthService.java]"]
  node_otp_service["OTP Service<br/>[OtpService.java]"]
  node_refresh_service["Refresh Sessions"]
  node_token_service["JWT Tokens<br/>[TokenService.java]"]
  node_user_store[("User Accounts<br/>[UserEntity.java]")]
  node_app_config["App Identity &amp; Config"]
end

subgraph group_content["Story Content"]
  node_catalogue["Public Catalogue"]
  node_content_admin["Content Workflow"]
  node_content_store[("Story Metadata")]
  node_chapter_store[("Chapter Metadata")]
  node_content_docs[("Story &amp; Chapter Documents")]
  node_import_service["Story Import"]
end

subgraph group_commerce["Access &amp; Billing"]
  node_access_service["Access Decisions"]
  node_entitlements[("Entitlements")]
  node_billing_service["Purchase Verification"]
  node_purchase_store[("Purchases")]
end

subgraph group_reader["Reader Features"]
  node_reading_api["Reading &amp; Annotations"]
  node_rating_service["Ratings &amp; Reviews<br/>[RatingService.java]"]
  node_rating_store[("Ratings<br/>[RatingEntity.java]")]
  node_support_service["Reader Support"]
  node_offline["Offline Manifests"]
end

subgraph group_operations["Administration"]
  node_admin_auth["Admin Authentication"]
  node_admin_api["Admin APIs"]
  node_audit_service["Audit Logging<br/>[AuditService.java]"]
  node_analytics["Usage Events"]
end

node_reader_actor(("Reader"))
node_admin_actor(("Administrator"))
node_google_play["Google Play"]

node_reader_actor -.->|"authenticates"| node_auth_api
node_auth_api -.->|"handles auth"| node_auth_service
node_auth_service -->|"reads/writes"| node_user_store
node_auth_service -->|"verifies OTP"| node_otp_service
node_auth_service -->|"issues sessions"| node_refresh_service
node_auth_service -->|"creates tokens"| node_token_service
node_admin_actor -.->|"operates"| node_admin_api
node_admin_api -.->|"authenticates"| node_admin_auth
node_reader_actor -.->|"browses stories"| node_catalogue
node_catalogue -.->|"reads stories"| node_content_store
node_admin_actor -.->|"manages stories"| node_content_admin
node_content_admin -->|"writes metadata"| node_content_store
node_content_admin -->|"writes metadata"| node_chapter_store
node_content_admin -->|"stores content"| node_content_docs
node_import_service -->|"delegates content"| node_content_admin
node_reader_actor -.->|"requests access"| node_access_service
node_access_service -->|"checks grants"| node_entitlements
node_reader_actor -.->|"verifies purchase"| node_billing_service
node_billing_service -->|"records purchase"| node_purchase_store
node_billing_service -->|"verifies purchase"| node_google_play
node_billing_service -->|"grants access"| node_entitlements
node_reader_actor -.->|"tracks reading"| node_reading_api
node_reader_actor -.->|"rates stories"| node_rating_service
node_rating_service -->|"reads/writes"| node_rating_store
node_reader_actor -.->|"requests support"| node_support_service
node_reader_actor -.->|"sends events"| node_analytics
node_reader_actor -.->|"requests manifest"| node_offline
node_admin_actor -.->|"audited actions"| node_audit_service

click node_auth_api "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/api/AuthController.java"
click node_auth_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/application/AuthService.java"
click node_otp_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/application/OtpService.java"
click node_refresh_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/application/RefreshTokenService.java"
click node_token_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/security/TokenService.java"
click node_user_store "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/persistence/UserEntity.java"
click node_app_config "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/appconfig/api/AppRequestContext.java"
click node_catalogue "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/application/CatalogueService.java"
click node_content_admin "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java"
click node_content_store "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/persistence/StoryRepository.java"
click node_chapter_store "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/persistence/ChapterRepository.java"
click node_content_docs "https://github.com/aditisingh-05/historia-backend/tree/main/src/main/java/com/bitverse/historia/content/persistence/mongo"
click node_import_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/importing/application/StoryImportService.java"
click node_access_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/entitlement/application/AccessDecisionService.java"
click node_entitlements "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/entitlement/persistence/EntitlementEntity.java"
click node_billing_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/billing/application/BillingService.java"
click node_purchase_store "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/billing/persistence/PurchaseEntity.java"
click node_reading_api "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/reading/api/ReadingStateController.java"
click node_rating_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/rating/application/RatingService.java"
click node_rating_store "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/rating/persistence/RatingEntity.java"
click node_support_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/support/application/SupportService.java"
click node_admin_auth "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/admin/application/AdminAuthService.java"
click node_admin_api "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/admin/api/AdminOperationsController.java"
click node_audit_service "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/admin/audit/AuditService.java"
click node_analytics "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/analytics/api/EventController.java"
click node_offline "https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/offline/api/OfflineManifestController.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_api,node_auth_service,node_otp_service,node_refresh_service,node_token_service,node_user_store,node_app_config toneBlue
class node_catalogue,node_content_admin,node_content_store,node_chapter_store,node_content_docs,node_import_service toneAmber
class node_access_service,node_entitlements,node_billing_service,node_purchase_store toneMint
class node_reading_api,node_rating_service,node_rating_store,node_support_service,node_offline toneRose
class node_admin_auth,node_admin_api,node_audit_service,node_analytics,node_reader_actor,node_admin_actor,node_google_play toneIndigo
```

## Components

### Identity & Platform

- [Auth API](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/api/AuthController.java): `src/main/java/com/bitverse/historia/auth/api/AuthController.java`
- [Reader Auth](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/application/AuthService.java): `src/main/java/com/bitverse/historia/auth/application/AuthService.java`
- [OTP Service](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/application/OtpService.java): `src/main/java/com/bitverse/historia/auth/application/OtpService.java`
- [Refresh Sessions](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/application/RefreshTokenService.java): `src/main/java/com/bitverse/historia/auth/application/RefreshTokenService.java`
- [JWT Tokens](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/security/TokenService.java): `src/main/java/com/bitverse/historia/auth/security/TokenService.java`
- [User Accounts](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/auth/persistence/UserEntity.java): `src/main/java/com/bitverse/historia/auth/persistence/UserEntity.java`
- [App Identity & Config](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/appconfig/api/AppRequestContext.java): `src/main/java/com/bitverse/historia/appconfig/api/AppRequestContext.java`

### Story Content

- [Public Catalogue](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/application/CatalogueService.java): `src/main/java/com/bitverse/historia/content/application/CatalogueService.java`
- [Content Workflow](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java): `src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java`
- [Story Metadata](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/persistence/StoryRepository.java): `src/main/java/com/bitverse/historia/content/persistence/StoryRepository.java`
- [Chapter Metadata](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/persistence/ChapterRepository.java): `src/main/java/com/bitverse/historia/content/persistence/ChapterRepository.java`
- [Story & Chapter Documents](https://github.com/aditisingh-05/historia-backend/tree/main/src/main/java/com/bitverse/historia/content/persistence/mongo): `src/main/java/com/bitverse/historia/content/persistence/mongo`
- [Story Import](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/content/importing/application/StoryImportService.java): `src/main/java/com/bitverse/historia/content/importing/application/StoryImportService.java`

### Access & Billing

- [Access Decisions](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/entitlement/application/AccessDecisionService.java): `src/main/java/com/bitverse/historia/entitlement/application/AccessDecisionService.java`
- [Entitlements](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/entitlement/persistence/EntitlementEntity.java): `src/main/java/com/bitverse/historia/entitlement/persistence/EntitlementEntity.java`
- [Purchase Verification](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/billing/application/BillingService.java): `src/main/java/com/bitverse/historia/billing/application/BillingService.java`
- [Purchases](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/billing/persistence/PurchaseEntity.java): `src/main/java/com/bitverse/historia/billing/persistence/PurchaseEntity.java`

### Reader Features

- [Reading & Annotations](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/reading/api/ReadingStateController.java): `src/main/java/com/bitverse/historia/reading/api/ReadingStateController.java`
- [Ratings & Reviews](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/rating/application/RatingService.java): `src/main/java/com/bitverse/historia/rating/application/RatingService.java`
- [Ratings](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/rating/persistence/RatingEntity.java): `src/main/java/com/bitverse/historia/rating/persistence/RatingEntity.java`
- [Reader Support](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/support/application/SupportService.java): `src/main/java/com/bitverse/historia/support/application/SupportService.java`
- [Offline Manifests](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/offline/api/OfflineManifestController.java): `src/main/java/com/bitverse/historia/offline/api/OfflineManifestController.java`

### Administration

- [Admin Authentication](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/admin/application/AdminAuthService.java): `src/main/java/com/bitverse/historia/admin/application/AdminAuthService.java`
- [Admin APIs](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/admin/api/AdminOperationsController.java): `src/main/java/com/bitverse/historia/admin/api/AdminOperationsController.java`
- [Audit Logging](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/admin/audit/AuditService.java): `src/main/java/com/bitverse/historia/admin/audit/AuditService.java`
- [Usage Events](https://github.com/aditisingh-05/historia-backend/blob/main/src/main/java/com/bitverse/historia/analytics/api/EventController.java): `src/main/java/com/bitverse/historia/analytics/api/EventController.java`

### Other components

- **Reader**
- **Administrator**
- **Google Play**

## Connections

- Reader → Auth API: authenticates (evidence: `README.md`)
- Auth API → Reader Auth: handles auth
- Reader Auth → User Accounts: reads/writes (evidence: `src/main/java/com/bitverse/historia/auth/application/AuthService.java`)
- Reader Auth → OTP Service: verifies OTP (evidence: `src/main/java/com/bitverse/historia/auth/application/AuthService.java`)
- Reader Auth → Refresh Sessions: issues sessions (evidence: `src/main/java/com/bitverse/historia/auth/application/AuthService.java`)
- Reader Auth → JWT Tokens: creates tokens (evidence: `src/main/java/com/bitverse/historia/auth/application/AuthService.java`)
- Administrator → Admin APIs: operates (evidence: `README.md`)
- Admin APIs → Admin Authentication: authenticates
- Reader → Public Catalogue: browses stories (evidence: `README.md`)
- Public Catalogue → Story Metadata: reads stories
- Administrator → Content Workflow: manages stories
- Content Workflow → Story Metadata: writes metadata (evidence: `src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java`)
- Content Workflow → Chapter Metadata: writes metadata (evidence: `src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java`)
- Content Workflow → Story & Chapter Documents: stores content (evidence: `src/main/java/com/bitverse/historia/content/application/ContentWorkflowService.java`)
- Story Import → Content Workflow: delegates content (evidence: `src/main/java/com/bitverse/historia/content/importing/application/StoryImportService.java`)
- Reader → Access Decisions: requests access
- Access Decisions → Entitlements: checks grants (evidence: `src/main/java/com/bitverse/historia/entitlement/application/AccessDecisionService.java`)
- Reader → Purchase Verification: verifies purchase
- Purchase Verification → Purchases: records purchase (evidence: `src/main/java/com/bitverse/historia/billing/application/BillingService.java`)
- Purchase Verification → Google Play: verifies purchase (evidence: `src/main/java/com/bitverse/historia/billing/application/BillingService.java`)
- Purchase Verification → Entitlements: grants access (evidence: `src/main/java/com/bitverse/historia/billing/application/BillingService.java`)
- Reader → Reading & Annotations: tracks reading
- Reader → Ratings & Reviews: rates stories
- Ratings & Reviews → Ratings: reads/writes (evidence: `src/main/java/com/bitverse/historia/rating/application/RatingService.java`)
- Reader → Reader Support: requests support
- Reader → Usage Events: sends events
- Reader → Offline Manifests: requests manifest
- Administrator → Audit Logging: audited actions
