# cobrother-official/cobrother_backend architecture

> Architecture diagram of the GitHub repository cobrother-official/cobrother_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cobrother-official/cobrother_backend
- Repository: https://github.com/cobrother-official/cobrother_backend

## Overview

1. This repository is a production FastAPI backend for a multi-domain marketplace platform called CoBrother. It serves authentication, domain registration/transfer, venture listings and deals, technology/cocreation sales, creator/community features, auctions, payments, analytics, admin operations, and real-time notifications.

2. The top-level runtime entrypoint is `app/main.py`, which assembles the FastAPI app, middleware, lifespan tasks, and route registration. Cross-cutting concerns live in `app/core/` and include configuration, database session wiring, auth dependencies, rate limiting, security, logging, request middleware, and bot protection.

3. The code follows a layered backend architecture: HTTP controllers in `app/controller/` receive requests; services in `app/service/` hold business rules and orchestration; repositories in `app/repository/` perform database access; SQLAlchemy entities in `app/entity/` define persistence models; Pydantic models in `app/model/` define request/response contracts. This separation is the main architectural boundary.

4. The system uses two database access paths, which is an important architectural split. `get_db` is the synchronous path used for auth, admin, analytics, meetings, and some ancillary workflows. `get_async_db` is the asynchronous path used heavily for auctions, ventures, domains, payments, and cocreation. Diagrammatically, this is a major boundary between request handling and persistence.

5. The application is organized into product subsystems rather than a generic CRUD structure. The major domains are auth/user management, domain marketplace and registration, venture/coventure management, technology/cocreation listings and software auctions, community/creator profiles and auctions, payments and payouts, analytics, notifications, and admin moderation. Each of these has its own controller/service/repository/entity stack.

6. Domain operations form one of the most complex flows. Controllers under `app/controller/domain/` call services such as registration, transfer, verification, escrow, dispute handling, and notifications. Those services integrate with registrar providers, WHOIS/RDAP lookups, GST/verification helpers, and payment/escrow logic. This subsystem also has marketplace-specific entities for listings, transactions, transfers, and disputes.

7. Venture and CoVenture are modeled as a separate business line with its own data and workflows. Controllers and services in `app/controller/venture/` and `app/service/venture/` handle venture listings, company profiles, financial profiles, pitches, deals, acquisition applications, and verification/GSTIN-related checks. The model is richer than simple listing CRUD and includes governance and deal lifecycle concepts.

8. Technology/cocreation covers software listings, auctions, purchases, completion, and verification. The controllers split between `technology` and `cocreation`, and the README notes some endpoints are dual-mounted for compatibility. Services here coordinate listing gates, auction participation, purchase completion, and payment flows, with dedicated entities for software, auctions, bids, participation, and payment status.

9. Community and creator features are another distinct subsystem. This includes communities, posts, comments, likes, follows, creator expected rate, meeting scheduling, and creator auctions. The meeting flow is especially important: bidders request meetings, the profile owner confirms through Google OAuth, and the system creates Google Calendar/Meet events and sends SMTP emails.

10. Payments and money movement are distributed across several verticals rather than centralized in one module. Razorpay is integrated for payments, while payout tracking and seller payout profiles live in dedicated payout services and entities. Domain registration, auctions, and software purchases each have payment-related states and transaction records, so payment behavior is embedded within the business flows instead of isolated.

11. Background and real-time behavior are first-class. `app/background_jobs.py` and lifecycle startup tasks handle auction expiry timers and scheduled cleanup/retry jobs. `app/websocket/` provides SockJS/STOMP-compatible channels for auction updates and notifications, with a connection manager and event routing layer. This means some state transitions are pushed asynchronously to clients rather than only returned via HTTP.

12. External integrations are concentrated under `app/integrations/` and materially shape the architecture. The backend talks to Google OAuth, Calendar, and Meet; SMTP mail; Razorpay; Supabase/S3-style storage; ResellerClub and OpenProvider domain registrars; Redis; GST validation; and WHOIS/RDAP services. These integrations are invoked by services, not controllers, keeping provider-specific logic out of the API layer.

13. Analytics and observability are implemented as product features, not just ops tooling. There are view-tracking entities and repositories for profile, venture, software, and domain listing views, plus analytics services and controller endpoints. This subsystem feeds reporting and ranking-style behavior across multiple product areas.

14. Alembic migrations are a major operational boundary. The repository contains a large migration history with many merge revisions, reflecting concurrent evolution of multiple domains. The README emphasizes maintaining a single Alembic head and blocking deploys if the schema graph diverges, so schema management is part of the production architecture.

15. Deployment and environment assumptions matter to the architecture. The app expects PostgreSQL, uses environment variables for secrets and external services, ships Docker and Nginx config examples, and includes CI/CD workflows for Alembic checks and deployment. Health and readiness endpoints support operational monitoring, while the tests are broad and domain-specific, reinforcing the service-oriented modular structure.

Main entry points: [`app/main.py`](https://github.com/cobrother-official/cobrother_backend/blob/main/app/main.py) (FastAPI app), [`app/integrations`](https://github.com/cobrother-official/cobrother_backend/tree/main/app/integrations) (Integrations), [`app/websocket/manager.py`](https://github.com/cobrother-official/cobrother_backend/blob/main/app/websocket/manager.py) (Realtime), [`app/controller/domain/domain_controller.py`](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/domain/domain_controller.py) (Domain market)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_main["FastAPI app<br/>entrypoint<br/>[main.py]"]
  node_background_jobs["Jobs<br/>scheduler<br/>[background_jobs.py]"]
end

subgraph group_core["Core"]
  node_core_config["Config<br/>settings<br/>[config.py]"]
  node_core_database[("Database<br/>db wiring<br/>[database.py]")]
  node_core_security["Security<br/>[security.py]"]
  node_core_middleware["Middleware"]
end

subgraph group_domains["Product domains"]
  node_auth_domain["Auth<br/>user access<br/>[auth_controller.py]"]
  node_domain_marketplace["Domain market<br/>domains"]
  node_venture_domain["Ventures<br/>business listings"]
  node_cocreation_domain["Cocreation<br/>software marketplace"]
  node_community_domain["Community"]
  node_payments_domain["Payments<br/>money flows"]
  node_analytics_domain["Analytics<br/>tracking"]
  node_admin_domain["Admin<br/>moderation"]
  node_notifications_domain["Notifications<br/>realtime alerts"]
  node_domain_layer["Domain services<br/>business services<br/>[domain_service.py]"]
  node_venture_layer["Venture services<br/>business services<br/>[venture_service.py]"]
  node_cocreation_layer["Cocreation services<br/>business services"]
  node_community_layer["Community services<br/>business services"]
end

subgraph group_infra["Infrastructure"]
  node_integrations["Integrations<br/>external adapters"]
  node_websocket["Realtime<br/>socket channels<br/>[manager.py]"]
  node_alembic["Migrations<br/>schema history<br/>[env.py]"]
end

node_app_main -->|"loads"| node_core_config
node_app_main -->|"wires"| node_core_database
node_app_main -->|"installs"| node_core_security
node_app_main -->|"adds"| node_core_middleware
node_app_main -->|"routes"| node_auth_domain
node_app_main -->|"routes"| node_domain_marketplace
node_app_main -->|"routes"| node_venture_domain
node_app_main -->|"routes"| node_cocreation_domain
node_app_main -->|"routes"| node_community_domain
node_app_main -->|"routes"| node_payments_domain
node_app_main -->|"routes"| node_analytics_domain
node_app_main -->|"routes"| node_admin_domain
node_app_main -->|"routes"| node_notifications_domain
node_app_main -->|"opens"| node_websocket
node_app_main -->|"starts"| node_background_jobs
node_domain_marketplace -->|"orchestrates"| node_domain_layer
node_venture_domain -->|"orchestrates"| node_venture_layer
node_cocreation_domain -->|"orchestrates"| node_cocreation_layer
node_community_domain -->|"orchestrates"| node_community_layer
node_domain_layer -->|"uses"| node_integrations
node_venture_layer -->|"uses"| node_integrations
node_cocreation_layer -->|"uses"| node_integrations
node_community_layer -->|"uses"| node_integrations
node_payments_domain -->|"uses"| node_integrations
node_websocket -->|"pushes"| node_notifications_domain
node_websocket -->|"attached to"| node_app_main
node_alembic -.->|"migrates"| node_core_database

click node_app_main "https://github.com/cobrother-official/cobrother_backend/blob/main/app/main.py"
click node_background_jobs "https://github.com/cobrother-official/cobrother_backend/blob/main/app/background_jobs.py"
click node_core_config "https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/config.py"
click node_core_database "https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/database.py"
click node_core_security "https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/security.py"
click node_core_middleware "https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/request_middleware.py"
click node_auth_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/auth/auth_controller.py"
click node_domain_marketplace "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/domain/domain_controller.py"
click node_venture_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/venture/venture_controller.py"
click node_cocreation_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/cocreation/cocreation_controller.py"
click node_community_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/community/community_controller.py"
click node_payments_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/payment/payment_controller.py"
click node_analytics_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/analytics/analytics_controller.py"
click node_admin_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/admin/admin_controller.py"
click node_notifications_domain "https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/notification/notification_controller.py"
click node_domain_layer "https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/domain/domain_service.py"
click node_venture_layer "https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/venture/venture_service.py"
click node_cocreation_layer "https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/cocreation/cocreation_service.py"
click node_community_layer "https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/community/community_service.py"
click node_integrations "https://github.com/cobrother-official/cobrother_backend/tree/main/app/integrations"
click node_websocket "https://github.com/cobrother-official/cobrother_backend/blob/main/app/websocket/manager.py"
click node_alembic "https://github.com/cobrother-official/cobrother_backend/blob/main/alembic/env.py"

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_app_main,node_background_jobs toneBlue
class node_core_config,node_core_database,node_core_security,node_core_middleware toneAmber
class node_auth_domain,node_domain_marketplace,node_venture_domain,node_cocreation_domain,node_community_domain,node_payments_domain,node_analytics_domain,node_admin_domain,node_notifications_domain,node_domain_layer,node_venture_layer,node_cocreation_layer,node_community_layer toneMint
class node_integrations,node_websocket,node_alembic toneRose
```

## Components

### Runtime

App entrypoint, lifecycle, and background execution

- [FastAPI app](https://github.com/cobrother-official/cobrother_backend/blob/main/app/main.py): entrypoint · Assembles middleware, lifespan tasks, and route registration · `app/main.py`
- [Jobs](https://github.com/cobrother-official/cobrother_backend/blob/main/app/background_jobs.py): scheduler · Startup and scheduled background tasks for timed workflows · `app/background_jobs.py`

### Core

Cross-cutting configuration, security, database, and middleware

- [Config](https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/config.py): settings · Environment, constants, and app configuration · `app/core/config.py`
- [Database](https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/database.py): db wiring · Sync and async session wiring and DB helpers · `app/core/database.py`
- [Security](https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/security.py): auth/security · Auth dependencies, cookies, rate limiting, and request protection · `app/core/security.py`
- [Middleware](https://github.com/cobrother-official/cobrother_backend/blob/main/app/core/request_middleware.py): http middleware · Request, logging, bot, and route middleware layers · `app/core/request_middleware.py`

### Product domains

Major business subsystems exposed through controllers and services

- [Auth](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/auth/auth_controller.py): user access · Authentication, token, profile completion, and account recovery · `app/controller/auth/auth_controller.py`
- [Domain market](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/domain/domain_controller.py): domains · Registration, transfer, enquiry, verification, escrow, and disputes · `app/controller/domain/domain_controller.py`
- [Ventures](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/venture/venture_controller.py): business listings · Venture, CoVenture, pitches, deals, and acquisition workflows · `app/controller/venture/venture_controller.py`
- [Cocreation](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/cocreation/cocreation_controller.py): software marketplace · Software listings, auctions, purchases, and completion flows · `app/controller/cocreation/cocreation_controller.py`
- [Community](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/community/community_controller.py): creator/community · Communities, posts, follows, meetings, and creator auctions · `app/controller/community/community_controller.py`
- [Payments](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/payment/payment_controller.py): money flows · Payment capture, fee handling, and payout-oriented operations · `app/controller/payment/payment_controller.py`
- [Analytics](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/analytics/analytics_controller.py): tracking · View tracking and analytics endpoints across product areas · `app/controller/analytics/analytics_controller.py`
- [Admin](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/admin/admin_controller.py): moderation · Administrative operations, fees, and domain registration oversight · `app/controller/admin/admin_controller.py`
- [Notifications](https://github.com/cobrother-official/cobrother_backend/blob/main/app/controller/notification/notification_controller.py): realtime alerts · Notification delivery and status endpoints · `app/controller/notification/notification_controller.py`
- [Domain services](https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/domain/domain_service.py): business services · Representative domain service layer handling orchestration and policy · `app/service/domain/domain_service.py`
- [Venture services](https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/venture/venture_service.py): business services · Representative venture service layer for listings, deals, and verification · `app/service/venture/venture_service.py`
- [Cocreation services](https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/cocreation/cocreation_service.py): business services · Representative cocreation service layer for software lifecycle and auctions · `app/service/cocreation/cocreation_service.py`
- [Community services](https://github.com/cobrother-official/cobrother_backend/blob/main/app/service/community/community_service.py): business services · Representative community service layer for posts, follows, meetings, and auctions · `app/service/community/community_service.py`

### Infrastructure

Integrations, realtime channels, and schema evolution

- [Integrations](https://github.com/cobrother-official/cobrother_backend/tree/main/app/integrations): external adapters · Google, Razorpay, registrars, mail, storage, Redis, GST, and WHOIS adapters · `app/integrations`
- [Realtime](https://github.com/cobrother-official/cobrother_backend/blob/main/app/websocket/manager.py): socket channels · SockJS/STOMP-compatible auction and notification channels · `app/websocket/manager.py`
- [Migrations](https://github.com/cobrother-official/cobrother_backend/blob/main/alembic/env.py): schema history · Operational database migration graph and Alembic environment · `alembic/env.py`

## Connections

- FastAPI app → Config: loads · Initializes runtime configuration from environment and constants
- FastAPI app → Database: wires · Creates sync and async persistence access for the app
- FastAPI app → Security: installs · Adds auth, rate limiting, and request protection concerns
- FastAPI app → Middleware: adds · Registers middleware and request logging layers
- FastAPI app → Auth: routes · Mounts authentication endpoints
- FastAPI app → Domain market: routes · Mounts domain marketplace endpoints
- FastAPI app → Ventures: routes · Mounts venture and CoVenture endpoints
- FastAPI app → Cocreation: routes · Mounts technology and cocreation endpoints
- FastAPI app → Community: routes · Mounts community and creator endpoints
- FastAPI app → Payments: routes · Mounts payment endpoints
- FastAPI app → Analytics: routes · Mounts analytics endpoints
- FastAPI app → Admin: routes · Mounts admin endpoints
- FastAPI app → Notifications: routes · Mounts notification endpoints
- FastAPI app → Realtime: opens · Starts realtime channels alongside HTTP
- FastAPI app → Jobs: starts · Runs scheduled timers and cleanup tasks
- Domain market → Domain services: orchestrates · HTTP controllers delegate marketplace rules to services
- Ventures → Venture services: orchestrates · Venture controllers delegate workflows to services
- Cocreation → Cocreation services: orchestrates · Cocreation controllers delegate workflows to services
- Community → Community services: orchestrates · Community controllers delegate workflows to services
- Domain services → Integrations: uses · Relies on registrar, WHOIS, GST, payment, and storage adapters
- Venture services → Integrations: uses · Relies on GST, mail, storage, and external API adapters
- Cocreation services → Integrations: uses · Relies on payments, storage, and verification adapters
- Community services → Integrations: uses · Relies on Google Meet/Calendar and mail adapters
- Payments → Integrations: uses · Calls payment and payout provider adapters
- Realtime → Notifications: pushes · Broadcasts notification events to clients
- Realtime → FastAPI app: attached to · Is hosted by the main application runtime
- Migrations → Database: migrates · Tracks schema state for the configured database