README

Cat Feeder Backend Manual Documentation

This directory contains comprehensive architectural documentation for the Cat Feeder Backend, organized to match the actual source code structure in backend/src/.

Attention

‍Most of the manual documentation you will read has been AI Generated and partially reviewed by humnans. This documentation is to take with a grain of salt but should never the less provide an overview of the inner workings of the project.

📚 Documentation Structure

Architecture Overview

File	Description
00_ARCHITECTURE.md	System architecture, design patterns, and module interactions

Project Structure

File	Description
project_structure.md	Directory structure, entry points, assets, dependencies
server_main.md	Entry point and CLI arguments

Module Documentation (maps to backend/src/libs/ and backend/src/config/)

Module	Description	Documentation
config/	Configuration & environment loading	config/config.md
server.py	Main Server orchestration	server/server.md
boilerplates/	Request/Response handlers	boilerplates/boilerplates.md
bucket/	S3 storage (MinIO)	bucket/bucket.md
core/	RuntimeManager, Singletons	core/core.md
crons/	Background tasks	crons/crons.md
docs/	API documentation	docs/docs.md
e_mail/	Email management	e_mail/e_mail.md
endpoint_manager/	Endpoint registration	endpoint_manager/endpoint_manager.md
fffamily/	FFmpeg utilities	fffamily/fffamily.md
http_codes/	HTTP status codes	http_codes/http_codes.md
path_manager/	Route management	path_manager/path_manager.md
redis/	Redis caching	redis/redis.md
server_header/	CORS, security headers	server_header/server_header.md
sql/	Database (MySQL)	sql/sql.md
utils/	OAuth, passwords, etc.	utils/utils.md

Additional Documentation

File	Description
QUICK_START.md	Quick start guide for development
00_ARCHITECTURE.md	Documentation overview

🎯 Purpose

This documentation serves multiple purposes:

1. Onboarding: Help new developers understand the system architecture
2. Reference: Provide detailed class and interaction diagrams
3. Design Documentation: Explain design patterns and architectural decisions
4. Doxygen Integration: Integrated into the main Doxygen-generated documentation

🔧 How to Use

For Developers

1. Start with the Overview: Read 00_ARCHITECTURE.md to understand the big picture
2. Dive into Layers: Explore specific layers based on your work area
3. Reference Diagrams: Use PlantUML diagrams to understand component interactions

For Doxygen Generation

See QUICK_START.md for a full quickstart. Key points summarized here:

# Make the generator scripts executable (one-time)
chmod +x doxygen_generation/generate_docs.sh doxygen_generation/make_documentation.sh
 
# Recommended: pull the prebuilt image first (fast, ~3-4 minutes)
docker pull hanralatalliard/doxygen:latest || true
 
# Then run the generator from the repository root; the script will pull or
# build the image as required (it prefers pulling the prebuilt image):
./doxygen_generation/generate_docs.sh
 
# Serve the generated HTML with an httpd Docker container (preferred):
docker run --rm --name Cat Feeder_docs -p 8080:80 \
   -v "$(pwd)/documentation/html":/usr/local/apache2/htdocs/:ro \
   httpd:2.4
# Open http://localhost:8080
 
# If your Docker requires root access, prefix with sudo:
sudo ./doxygen_generation/generate_docs.sh
sudo docker run --rm --name Cat Feeder_docs -p 8080:80 \
   -v "$(pwd)/documentation/html":/usr/local/apache2/htdocs/:ro \
   httpd:2.4
 
# WARNING: building the Docker image locally may trigger a full LaTeX
# toolchain build — compiling LaTeX/PDF artifacts from source can take
# several hours (~4h). Prefer pulling the prebuilt image and only build
# locally as a last resort.

The PlantUML diagrams will be rendered as images in the HTML output.

📊 Diagram Format: PlantUML

All diagrams use PlantUML syntax for the following reasons:

✅ Advantages:

• Text-based (perfect for version control)
• Native Doxygen support
• AI-friendly (easy to generate and modify)
• Renders to SVG/PNG automatically
• Consistent with Doxygen's automatic UML diagrams

Diagram Types Used

1. Component Diagrams: System architecture and module relationships
2. Class Diagrams: Class structure and inheritance
3. Sequence Diagrams: Interaction flows and message passing
4. Deployment Diagrams: Service initialization and dependencies

🏗️ Architecture Layers

The backend follows a layered architecture:

┌─────────────────────────────────────┐
│       Entry Point Layer             │  server_main.py
├─────────────────────────────────────┤
│       Application Layer             │  Server, PathManager, EndpointManager
├─────────────────────────────────────┤
│       Service Layer                 │  BackgroundTasks, OAuth, MailManagement
├─────────────────────────────────────┤
│       Data Layer                    │  SQL, Redis, Bucket (S3)
├─────────────────────────────────────┤
│       Core Layer                    │  RuntimeManager, FinalSingleton
├─────────────────────────────────────┤
│       Utility Layer                 │  Boilerplates, HttpCodes, Passwords
└─────────────────────────────────────┘

🔑 Key Design Patterns

1. Service Locator Pattern

Implementation: RuntimeManager

• Centralized service container
• Lazy initialization
• Thread-safe singleton management

2. Final Singleton Pattern

Implementation: FinalSingleton base class

• Prevents direct instantiation
• Enforces RuntimeManager usage
• Thread-safe creation

3. Path Registration Pattern

Implementation: PathManager

• Deferred route registration
• Decouples endpoints from FastAPI
• Enables route introspection

4. Boilerplate Pattern

Implementation: BoilerplateResponses / BoilerplateIncoming

• Standardized request/response handling
• Consistent error formats
• Validation decorators

📖 Reading Guide

For Backend Developers

1. Start: 00_ARCHITECTURE.md → 01_CORE.md
2. Then: 02_DATA_LAYER.md for database/caching
3. Then: 03_APPLICATION_LAYER.md for endpoint management

For Frontend Developers

1. Start: 00_ARCHITECTURE.md (high-level only)
2. Focus: 03_APPLICATION_LAYER.md → EndpointManager
3. Reference: API documentation at /docs endpoint

For DevOps Engineers

1. Start: 00_ARCHITECTURE.md → Architecture Diagram
2. Focus: Service initialization sequence
3. Reference: Docker configuration and deployment

For QA/Testing

1. Start: 00_ARCHITECTURE.md → Testing Strategy
2. Reference: Testing sections in each layer document
3. Focus: Mock implementations and test patterns

🛠️ Maintenance

Adding New Documentation

When adding new modules:

1. Create new .md file following naming convention
2. Include PlantUML diagrams for:
   • Class structure
   • Interaction flows
   • Integration points
3. Link from related documents
4. Update this README

Updating Diagrams

PlantUML diagrams can be edited directly in the .md files:

@startuml
' Edit diagram here
@enduml

After editing, regenerate Doxygen documentation to see rendered diagrams.

🔗 Links

• Main Doxygen Docs: ../doxygen_generation/documentation/html/index.html (after generation)
• Source Code: ../backend/src/libs/
• API Documentation: http://localhost:5000/docs (when server running)
• PlantUML Documentation: https://plantuml.com/

Note about live API documentation endpoints: The live API documentation endpoints (for example http://localhost:5000/docs, http://localhost:5000/redoc, http://localhost:5000/rapidpdf, http://localhost:5000/scalar, http://localhost:5000/editor, http://localhost:5000/elements, http://localhost:5000/explorer) are only available when the corresponding documentation endpoints are enabled in your project's .env configuration. Check sample.env or your environment settings and enable the API docs features before expecting these routes to be accessible.

📝 Document Conventions

Headers

• Use {#anchor_name} for Doxygen anchors
• Use hierarchical numbering for sections

Code Blocks

• Use language-specific syntax highlighting
• Include explanatory comments
• Provide context before/after code

Diagrams

• Always include !theme plain for consistency
• Add notes for complex interactions
• Use meaningful component names

Links

• Use relative links for local files
• Use Doxygen \ref for cross-references
• Always verify links after generation

🤝 Contributing

When contributing to this documentation:

1. Accuracy: Ensure diagrams match actual code
2. Clarity: Write for multiple audiences (junior devs to architects)
3. Completeness: Cover common use cases and edge cases
4. Consistency: Follow existing formatting and style
5. Testing: Generate Doxygen to verify rendering

📅 Version History

Version	Date	Changes
1.0.0	2025-12-02	Initial comprehensive documentation created

---

Questions? Check the Overview or consult the generated Doxygen documentation.