# crushr3sist/r3almx-backend architecture

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

- Interactive diagram: https://gitdiagram.com/crushr3sist/r3almx-backend
- Repository: https://github.com/crushr3sist/r3almx-backend

## Overview

##### Project Type and Purpose
- This is a backend microservices-based architecture built to support a dynamic, real-time online platform. The system architecture is modular and is divided into distinct services (auth, chat, friends, posts, realtime, search, etc.) that work together to power functionalities like user authentication, room/channel management, messaging, notifications, content moderation, and more.
- The README emphasizes scalability, real-time communication (e.g., via WebSockets and RabbitMQ), and a plugin system for extensibility.

##### Analyzing the File Structure
- Top-Level Files: Notice containerization (Dockerfile, docker-compose.yaml, fly.toml) and configuration files (pyproject.toml, requirements.txt) indicating deployment and dependency management.
- The “r3almX_backend” directory contains multiple service directories such as:
- auth_service: Handles user authentication and authorization.
- chat_service: Manages chat functionalities including submodules for channels, invites, and room management.
- friends_service: Manages friend/invitation system.
- post_service: Handles posts and related operations.
- realtime_service: Likely supports real-time data exchange using WebSockets and message queues.
- search_service: Provides search capabilities.
- user_state_service: Manages user state and other dynamic features.
- The dedicated “database” module indicates a layer for handling SQLAlchemy and PostgreSQL interactions.
- Other files like “hello.py”, “main.py”, and “vaulted_code” suggest some legacy or test scripts but the core components are in the structured directories.

##### Key Components
a. Service Components:
- Auth Service (user authentication/authorization)
- Chat Service (which further splits into:
- Channel System (channel management)
- Invite System (room/friends invites)
- Room Service (user-created rooms)
)
- Friends Service (friends/invitation handling)
- Post Service (content creation and management)
- Realtime Service (real-time communication, messaging)
- Search Service (search functionality across rooms, channels, etc.)
- Additional modules (e.g., user_state_service, potential Notification or Media services mentioned in the README’s philosophy though not explicitly structured in the file tree)
- Database Layer (SQLAlchemy with PostgreSQL)
- Integration of caching and messaging (Redis and RabbitMQ as denoted in the README’s Technology Stack)

b. Relationships and Interactions:
- Input/output flows:
- Authentication flows from Auth Service to the rest of the system.
- Chat and Realtime Services handle messaging, aided by RabbitMQ for asynchronous communication.
- Data flows between each service’s business logic and the common Database module.
- Web client interactions (even though primarily a backend, external requests likely go to an API layer built with FastAPI).
- Cross-module interactions such as:
- Notification triggers from events in Chat, Friends, and Post Services.
- Invitation flows across Auth, Chat, and Friends Services.
- Search queries hitting the Search Service which interacts with data from various service databases.

##### Architectural Patterns and Design Principles
- Microservices Architecture: Each service is encapsulated in its own module, ideally deployed independently (as suggested by container orchestration files).
- Modular design: Each domain (auth, chat, etc.) has its own package structure, allowing for separation of concerns.
- Database abstraction: A shared database layer handled by SQLAlchemy.
- Containerization and CI/CD: Docker-related files and GitHub workflows indicate automated deployments and code quality checks, which can be illustrated as an envelope around the system deployment environment.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Clients
    WebClient["Web Client"]:::client
    APIGateway["API Gateway"]:::gateway

    %% Microservices Group
    subgraph "Microservices"
        AuthService["Auth Service"]:::service
        subgraph "Chat Service"
            ChatService["Chat Service"]:::service
            ChannelSystem["Channel System"]:::subservice
            InviteSystem["Invite System"]:::subservice
            RoomService["Room Service"]:::subservice
        end
        FriendsService["Friends Service"]:::service
        PostService["Post Service"]:::service
        RealtimeService["Realtime Service"]:::service
        SearchService["Search Service"]:::service
        UserStateService["User State Service"]:::service
    end

    %% Infrastructure Group
    subgraph "Infrastructure"
        DatabaseLayer["Database Layer"]:::database
        RabbitMQ["RabbitMQ"]:::messaging
        Redis["Redis"]:::cache
        Docker["Docker & Compose"]:::container
    end

    %% External Flow: Client to API Gateway
    WebClient -->|"APIRequest"| APIGateway

    %% API Gateway to Microservices
    APIGateway -->|"AuthReq"| AuthService
    APIGateway -->|"ChatReq"| ChatService
    APIGateway -->|"FriendsReq"| FriendsService
    APIGateway -->|"PostReq"| PostService
    APIGateway -->|"RealtimeReq"| RealtimeService
    APIGateway -->|"SearchReq"| SearchService
    APIGateway -->|"UserStateReq"| UserStateService

    %% Microservices to Database Layer (common data access)
    AuthService -->|"DBCalls"| DatabaseLayer
    ChatService -->|"DBCalls"| DatabaseLayer
    FriendsService -->|"DBCalls"| DatabaseLayer
    PostService -->|"DBCalls"| DatabaseLayer
    RealtimeService -->|"DBCalls"| DatabaseLayer
    SearchService -->|"DBCalls"| DatabaseLayer
    UserStateService -->|"DBCalls"| DatabaseLayer

    %% Messaging Interactions
    RealtimeService -->|"Messaging"| RabbitMQ
    ChatService -->|"Messaging"| RabbitMQ

    %% Containerization - Deployment Context
    Docker -->|"Containerized"| APIGateway
    Docker -->|"Containerized"| AuthService
    Docker -->|"Containerized"| ChatService
    Docker -->|"Containerized"| FriendsService
    Docker -->|"Containerized"| PostService
    Docker -->|"Containerized"| RealtimeService
    Docker -->|"Containerized"| SearchService
    Docker -->|"Containerized"| UserStateService
    Docker -->|"Containerized"| DatabaseLayer
    Docker -->|"Containerized"| RabbitMQ
    Docker -->|"Containerized"| Redis

    %% Click Events
    click AuthService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/auth_service/"
    click ChatService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/chat_service/"
    click ChannelSystem "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/chat_service/channel_system/"
    click InviteSystem "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/chat_service/invite_system/"
    click RoomService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/chat_service/room_service/"
    click FriendsService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/friends_service/"
    click PostService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/post_service/"
    click RealtimeService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/realtime_service/"
    click SearchService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/search_service/"
    click UserStateService "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/user_state_service/"
    click DatabaseLayer "https://github.com/crushr3sist/r3almx-backend/tree/main/r3almX_backend/database/"

    %% Styles
    classDef client fill:#f9f,stroke:#333,stroke-width:2px;
    classDef gateway fill:#ccf,stroke:#333,stroke-width:2px;
    classDef service fill:#cfc,stroke:#333,stroke-width:2px;
    classDef subservice fill:#efe,stroke:#333,stroke-width:2px;
    classDef database fill:#ffc,stroke:#333,stroke-width:2px;
    classDef messaging fill:#fc9,stroke:#333,stroke-width:2px;
    classDef cache fill:#cff,stroke:#333,stroke-width:2px;
    classDef container fill:#fcc,stroke:#333,stroke-width:2px;
```
