Backend Class Diagram

StoryBridge Backend Class Diagram Information

Overview

This document contains a comprehensive list of all classes, methods, and relationships for the StoryBridge backend codebase. This information is suitable for creating a detailed class diagram.

---

1. MODELS (Database Models)

1.1 User Model

Class: User(models.Model)

• Primary Key: uid: UUIDField
• Fields:
  • device_info: CharField(max_length=255, unique=True)
  • language_preference: CharField(max_length=20, default="en")
  • created_at: DateTimeField
  • updated_at: DateTimeField
• Methods:
  • __str__() - String representation
  • getSessions() - Returns all sessions for the user
  • deleteSession(session_id) - Deletes a specific session
• Relationships:
  • One-to-Many: User → Session (reverse name: "sessions")

---

1.2 Session Model

Class: Session(models.Model)

• Primary Key: id: UUIDField
• Fields:
  • user: ForeignKey(User, on_delete=CASCADE, related_name="sessions")
  • title: CharField(max_length=255)
  • translated_title: CharField(max_length=255, nullable)
  • cover_img_url: TextField(nullable)
  • created_at: DateTimeField
  • started_at: DateTimeField
  • ended_at: DateTimeField(nullable)
  • isOngoing: BooleanField(default=True)
  • totalPages: IntegerField(default=0)
  • totalWords: IntegerField(default=0)
  • voicePreference: CharField(max_length=50, nullable)
• Methods:
  • __str__() - String representation
  • getPages() - Returns all pages in the session
  • addPage(img_url, index=None) - Helper method to add a page
• Relationships:
  • Many-to-One: Session → User
  • One-to-Many: Session → Page (reverse name: "pages")

---

1.3 Page Model

Class: Page(models.Model)

• Primary Key: id: AutoField
• Fields:
  • session: ForeignKey(Session, on_delete=CASCADE, related_name="pages")
  • img_url: TextField(nullable)
  • audio_url: TextField(nullable)
  • translation_text: TextField(nullable)
  • bbox_json: JSONField(default=dict)
  • created_at: DateTimeField
• Methods:
  • __str__() - String representation
  • getBBs() - Returns all bounding boxes for the page
  • addBB(bbox_list, translated_list, audio_list) - Helper to add bounding boxes
• Relationships:
  • Many-to-One: Page → Session
  • One-to-Many: Page → BB (reverse name: "bbs")

---

1.4 BB (Bounding Box) Model

Class: BB(models.Model)

• Primary Key: id: AutoField (implicit)
• Fields:
  • page: ForeignKey(Page, on_delete=CASCADE, related_name="bbs")
  • original_text: TextField
  • translated_text: TextField(nullable)
  • audio_base64: JSONField(default=list) - Stores list of base64-encoded audio clips
  • coordinates: JSONField(default=dict) - Stores {x1, y1, x2, y2, x3, y3, x4, y4}
  • tts_status: CharField(max_length=20, choices=["pending", "processing", "ready", "failed"])
• Methods:
  • __str__() - String representation
• Relationships:
  • Many-to-One: BB → Page

---

2.2 Session Controller

Class: StartSessionView(APIView)

• Endpoint: POST /session/start
• Methods:
  • post(request) - Start a new reading session
    • Input: {user_id, page_index=0}
    • Output: {session_id, started_at, page_index}
    • Status Codes: 200, 400, 404, 500

Class: SelectVoiceView(APIView)

• Endpoint: POST /session/voice
• Methods:
  • post(request) - Set voice preference for a session
    • Input: {session_id, voice_style}
    • Output: {session_id, voice_style}
    • Status Codes: 200, 400, 404

Class: EndSessionView(APIView)

• Endpoint: POST /session/end
• Methods:
  • post(request) - End a reading session
    • Input: {session_id}
    • Output: {session_id, ended_at, total_pages}
    • Status Codes: 200, 400, 404

Class: GetSessionStatsView(APIView)

• Endpoint: GET /session/stats
• Methods:
  • get(request) - Get comprehensive session statistics
    • Input: Query params: {session_id}
    • Output: {session_id, user_id, voice_style, isOngoing, started_at, ended_at, total_pages, total_time_spent, total_words_read}
    • Status Codes: 200, 400, 404

Class: SessionReloadAllView(APIView)

• Endpoint: GET /session/reload_all
• Methods:
  • get(request) - Reload entire session with all pages
    • Input: Query params: {user_id, started_at}
    • Output: {session_id, started_at, pages: [{page_index, image_base64, translation_text, audio_url, ocr_results: [{text, translated_text, audio_base64, coordinates}]}]}
    • Status Codes: 200, 400, 404, 500

Class: DiscardSessionView(APIView)

• Endpoint: POST /session/discard
• Methods:
  • post(request) - Delete session and all related data
    • Input: {session_id}
    • Output: {message}
    • Status Codes: 200, 400, 404, 500

---

6. API ENDPOINT SUMMARY

User Endpoints

• POST /user/register
• POST /user/login
• PATCH /user/lang
• GET /user/info

Session Endpoints

• POST /session/start
• POST /session/voice
• POST /session/end
• GET /session/stats
• GET /session/reload_all
• POST /session/discard

Page Endpoints

• GET /page/get_image
• GET /page/get_ocr
• GET /page/get_tts

Process Endpoints

• POST /process/upload
• GET /process/check_ocr
• GET /process/check_tts
• POST /process/upload_cover
• POST /process/word_picker

---

7. KEY FEATURES AND PATTERNS

7.1 Image Processing Pipeline

1. Image upload (base64) → Save to disk
2. OCR processing → Extract text and bounding boxes
3. Translation → Translate text to target language
4. Sentiment analysis → Analyze emotional tone
5. TTS generation → Generate audio with sentiment-based instructions

7.2 Cover Image Processing

1. Cover image upload → OCR to extract title
2. Translate title
3. Generate TTS for both male and female voices simultaneously

7.3 Word Count Tracking

• Session tracks total words read
• Words are counted from OCR results and accumulated per session

7.4 Session Management

• Sessions can be started, ended, or discarded
• Pages are associated with sessions (One-to-Many)
• Sessions track metadata: title, voice preference, total pages, total words

7.5 Profanity Filtering

• Profanity word lists loaded at Django app startup (ApisConfig.ready())
• Applied automatically during translation process
• Supports English, Chinese, and Vietnamese
• Removes detected profanity words using regex pattern matching
• Transparent to API consumers (no changes to response format)

7.6 Key Vocabulary Extraction

• Extracts 3 important words using an LLM.
• Activates only when the translated text has 20+ words.
• For each word, the system provides the original form and its Korean meaning.
• Stored in the session and shown to the user at session end for quick review.