# ajil2545/auditbook-backend architecture

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

- Interactive diagram: https://gitdiagram.com/ajil2545/auditbook-backend
- Repository: https://github.com/ajil2545/auditbook-backend

## Overview

##### Project type & purpose (from file tree + README)
This is a **Python 3.13 backend service** called **AuditBook** (“പരിപാടി ഓഡിറ്റ് ബുക്ക്” = event/program audit book). The structure strongly suggests a **REST API** that supports:
- **User management** (`scripts/core/services/user_management.py`, `handlers/user_handler.py`, `collections/users.py`, `schema/user.py`)
- **Auditing / audit book records** (`services/auditing.py`, `collections/auditing.py`, `schema/audit.py`)
- Likely **book/data records** (`collections/books.py`, `handlers/data_handler.py`)
- Persistence in **MongoDB** (entire `scripts/database/mongodb/...` subtree)
- Runtime configuration via YAML (`conf/config.yml`)
- Containerized deployment (`Dockerfile`, `docker-compose.yml`)
- Some interaction with an **Excel seed/source file** (`assets/red_book.xlsx`)
- Potential **email notifications** (`scripts/utils/email_util.py`)

##### Entry points / deployment
- `app.py` → main application entry (web server initialization, routing registration)
- `Dockerfile` → container build of the API
- `docker-compose.yml` → multi-container runtime (very likely API + MongoDB)
- `requirements.txt` → runtime dependencies (framework, pymongo, etc.)

##### Configuration
- `conf/config.yml` + `scripts/utils/config_reader.py` → environment/config loading

##### API surface and routing
- `scripts/constants/api_endpoints.py` → canonical list of API routes (useful for labeling “API” boundaries)
- `scripts/schema/*` → request/response models (DTOs), e.g. `schema/response.py`, `schema/user.py`, `schema/audit.py`

##### Application / business logic layers
- **Handlers**: `scripts/core/handlers/*`
Think “controller layer”: translate HTTP request → call services → return response
- `data_handler.py`
- `user_handler.py`
- **Services**: `scripts/core/services/*`
Think “domain logic”:
- `auditing.py`
- `user_management.py`

##### Data access layer (MongoDB)
- `scripts/database/mongodb/audit_book/collections/*` → concrete collection access modules:
- `users.py`
- `auditing.py`
- `books.py`
- `scripts/utils/mongo_util.py`, `scripts/utils/mongo_tools/mongo_sync.py` → connection utilities / sync/maintenance tooling

##### Cross-cutting utilities
- `scripts/utils/logger.py` → logging
- `scripts/utils/common_util.py`, `user_util.py` → shared helpers
- `scripts/utils/email_util.py` → outbound email integration

##### Tests
- `tests/test_api.py` → API-level tests (good for validating which endpoints exist and critical flows)

Shows: Client(s), API container, MongoDB container, and any external dependencies (SMTP/email).

Shows: routes/endpoints → handlers → services → repositories/collections → MongoDB, plus schema/utilities.

- **User / Admin / Client** (web/mobile/Postman)
- **AuditBook API (Python container)**
- Contains: app.py + handlers/services/schemas/utils
- **MongoDB (DB container or managed MongoDB)**
- Stores: users, auditing, books collections
- **SMTP / Email Provider** (external)
- API → SMTP (for notifications/verification/etc., if used)
- **Config Source** (YAML file / environment variables)
- API reads config at startup
- **Assets / Excel** (optional, but include if it is part of runtime workflows)
- API may read/import `assets/red_book.xlsx` (if used by `data_handler` flows)

- Client → API (request)
- API → Client (response)
- API → MongoDB (CRUD)
- API → SMTP (send email)
- API → Assets (read/import)
- API → Config (read)

Inside the API container, split into these components (use the directory names as labels):

##### API Layer
- “Routes/Endpoints” (from `constants/api_endpoints.py` and whatever framework wiring exists in `app.py`)

##### Handlers (Controller Layer)
- `DataHandler` (`scripts/core/handlers/data_handler.py`)
- `UserHandler` (`scripts/core/handlers/user_handler.py`)

##### Services (Domain Layer)
- `AuditingService` (`scripts/core/services/auditing.py`)
- `UserManagementService` (`scripts/core/services/user_management.py`)

##### Data Access Layer
- `UsersCollection` (`collections/users.py`)
- `AuditingCollection` (`collections/auditing.py`)
- `BooksCollection` (`collections/books.py`)

##### Schemas / DTOs
- `schema/user.py`, `schema/audit.py`, `schema/response.py`
- Use these as “contracts” between Handler and outside world; optionally show them as a “shared library” component.

##### Utilities (Cross-cutting)
- Config: `config_reader.py`
- Mongo utilities: `mongo_util.py`, `mongo_sync.py`
- Logging: `logger.py`
- Common/user helpers: `common_util.py`, `user_util.py`
- Email: `email_util.py`

##### Important architectural patterns to highlight
From the structure, the codebase follows a fairly standard layered approach:

- **Controller/Handler → Service → Repository/Collection → Database**
- “Schema” modules act as **API contracts** (request/response models)
- “Utils” provide **cross-cutting concerns** (logging, config, DB connection, email)
- “Constants” define **stable interface points** (endpoints, app constants, db constants)

- Making “utils” a side band that many components depend on (fan-in dependencies)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 1: Container Diagram
    %% =========================
    subgraph "AuditBook System (Runtime / Deployment)"
        direction TB

        Client["Client (Web/Mobile/Postman)"]:::external

        subgraph "Containerization"
            direction TB
            Compose["docker-compose.yml\nMulti-container runtime"]:::ops
            Docker["Dockerfile\nAPI image build"]:::ops
        end

        subgraph "AuditBook API Container (Python 3.13)"
            direction TB
            App["app.py\nComposition root / Web server"]:::api

            ConfigYml["conf/config.yml\nRuntime configuration"]:::config

            Assets["assets/red_book.xlsx\nExcel seed/source (optional)"]:::optional

            subgraph "API Surface"
                direction TB
                Endpoints["scripts/constants/api_endpoints.py\nRoutes/Endpoints registry"]:::api
                AppConst["scripts/constants/app_constants.py\nApp constants"]:::config
                DbConst["scripts/constants/db_constants.py\nDB constants"]:::config
            end

            subgraph "Handler Layer (Controllers)"
                direction TB
                HandlersDir["scripts/core/handlers/"]:::api
                DataHandler["DataHandler\nscripts/core/handlers/data_handler.py"]:::api
                UserHandler["UserHandler\nscripts/core/handlers/user_handler.py"]:::api
            end

            subgraph "Service Layer (Business Logic)"
                direction TB
                ServicesDir["scripts/core/services/"]:::service
                AuditingSvc["AuditingService\nscripts/core/services/auditing.py"]:::service
                UserMgmtSvc["UserManagementService\nscripts/core/services/user_management.py"]:::service
            end

            subgraph "Schema / DTO Models (API Contracts)"
                direction TB
                SchemaDir["scripts/schema/"]:::schema
                UserSchema["scripts/schema/user.py\nUser DTOs"]:::schema
                AuditSchema["scripts/schema/audit.py\nAudit DTOs"]:::schema
                ResponseSchema["scripts/schema/response.py\nResponse DTOs"]:::schema
            end

            subgraph "Utilities (Cross-cutting)"
                direction TB
                ConfigReader["scripts/utils/config_reader.py\nLoadConfig()"]:::util
                Logger["scripts/utils/logger.py\nLogging"]:::util
                CommonUtil["scripts/utils/common_util.py\nHelpers"]:::util
                UserUtil["scripts/utils/user_util.py\nUser helpers"]:::util
                EmailUtil["scripts/utils/email_util.py\nSMTP client"]:::integration
                MongoUtil["scripts/utils/mongo_util.py\nMongo connection/util"]:::util
                MongoSync["scripts/utils/mongo_tools/mongo_sync.py\nSync/Maintenance tool"]:::optional
            end

            subgraph "MongoDB Data Access (Collections/DAO)"
                direction TB
                CollectionsDir["scripts/database/mongodb/audit_book/collections/"]:::data
                UsersCol["UsersCollection\n.../collections/users.py"]:::data
                AuditingCol["AuditingCollection\n.../collections/auditing.py"]:::data
                BooksCol["BooksCollection\n.../collections/books.py"]:::data
            end
        end

        MongoDB[("MongoDB\n(users, auditing, books collections)")]:::db
        SMTP["SMTP / Email Provider (External)"]:::external

        Tests["tests/test_api.py\nAPI-level tests"]:::test
        Requirements["requirements.txt\nRuntime dependencies"]:::ops
    end

    %% Container-level connections
    Client -->|"HTTPS REST calls"| App
    App -->|"registerRoutes()"| Endpoints
    App -->|"loadConfig()"| ConfigReader
    ConfigReader -->|"read"| ConfigYml

    Endpoints -->|"dispatchToHandlers"| DataHandler
    Endpoints -->|"dispatchToHandlers"| UserHandler

    DataHandler -->|"callDomainLogic()"| AuditingSvc
    DataHandler -->|"callDomainLogic()"| UserMgmtSvc
    UserHandler -->|"callDomainLogic()"| UserMgmtSvc
    UserHandler -->|"callDomainLogic()"| AuditingSvc

    DataHandler <-->|"validate/serialize"| SchemaDir
    UserHandler <-->|"validate/serialize"| SchemaDir
    SchemaDir --> UserSchema
    SchemaDir --> AuditSchema
    SchemaDir --> ResponseSchema

    AuditingSvc -->|"CRUD"| AuditingCol
    AuditingSvc -->|"CRUD"| BooksCol
    UserMgmtSvc -->|"CRUD"| UsersCol

    UsersCol -->|"useMongoClient"| MongoUtil
    AuditingCol -->|"useMongoClient"| MongoUtil
    BooksCol -->|"useMongoClient"| MongoUtil
    MongoUtil -->|"connect"| MongoDB

    AuditingSvc -->|"log"| Logger
    UserMgmtSvc -->|"log"| Logger
    DataHandler -->|"helpers"| CommonUtil
    UserHandler -->|"helpers"| UserUtil

    UserMgmtSvc -.->|"sendEmail() (optional)"| EmailUtil
    EmailUtil -.->|"SMTP"| SMTP

    DataHandler -.->|"import/read (optional)"| Assets

    MongoSync -.->|"sync/maintenance (optional)"| MongoDB

    Tests -->|"exerciseEndpoints"| Endpoints
    Requirements -->|"pinsDepsFor"| App
    Compose -->|"runs"| Docker
    Compose -->|"starts"| App
    Compose -->|"starts"| MongoDB

    %% =========================
    %% Styles
    %% =========================
    classDef external fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20
    classDef api fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0D47A1
    classDef service fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px,color:#0D47A1
    classDef schema fill:#EDE7F6,stroke:#5E35B1,stroke-width:1px,color:#311B92
    classDef data fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px,color:#E65100
    classDef db fill:#F3E5F5,stroke:#6A1B9A,stroke-width:2px,color:#4A148C
    classDef util fill:#ECEFF1,stroke:#546E7A,stroke-width:1px,color:#263238
    classDef config fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#F57F17
    classDef integration fill:#E0F7FA,stroke:#00838F,stroke-width:1px,color:#004D40
    classDef ops fill:#F5F5F5,stroke:#616161,stroke-width:1px,color:#212121
    classDef optional fill:#FAFAFA,stroke:#9E9E9E,stroke-dasharray: 5 5,stroke-width:1px,color:#424242
    classDef test fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#B71C1C

    %% =========================
    %% Click Events (component_mapping)
    %% =========================
    click App "https://github.com/ajil2545/auditbook-backend/blob/main/app.py"
    click Docker "https://github.com/ajil2545/auditbook-backend/tree/main/Dockerfile"
    click Compose "https://github.com/ajil2545/auditbook-backend/blob/main/docker-compose.yml"
    click Requirements "https://github.com/ajil2545/auditbook-backend/blob/main/requirements.txt"
    click ConfigYml "https://github.com/ajil2545/auditbook-backend/blob/main/conf/config.yml"
    click ConfigReader "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/utils/config_reader.py"
    click Endpoints "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/constants/api_endpoints.py"
    click AppConst "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/constants/app_constants.py"
    click DbConst "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/constants/db_constants.py"
    click HandlersDir "https://github.com/ajil2545/auditbook-backend/tree/main/scripts/core/handlers/"
    click DataHandler "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/core/handlers/data_handler.py"
    click UserHandler "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/core/handlers/user_handler.py"
    click ServicesDir "https://github.com/ajil2545/auditbook-backend/tree/main/scripts/core/services/"
    click AuditingSvc "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/core/services/auditing.py"
    click UserMgmtSvc "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/core/services/user_management.py"
    click CollectionsDir "https://github.com/ajil2545/auditbook-backend/tree/main/scripts/database/mongodb/audit_book/collections/"
    click UsersCol "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/database/mongodb/audit_book/collections/users.py"
    click AuditingCol "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/database/mongodb/audit_book/collections/auditing.py"
    click BooksCol "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/database/mongodb/audit_book/collections/books.py"
    click MongoUtil "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/utils/mongo_util.py"
    click MongoSync "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/utils/mongo_tools/mongo_sync.py"
    click SchemaDir "https://github.com/ajil2545/auditbook-backend/tree/main/scripts/schema/"
    click UserSchema "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/schema/user.py"
    click AuditSchema "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/schema/audit.py"
    click ResponseSchema "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/schema/response.py"
    click Logger "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/utils/logger.py"
    click CommonUtil "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/utils/common_util.py"
    click UserUtil "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/utils/user_util.py"
    click EmailUtil "https://github.com/ajil2545/auditbook-backend/blob/main/scripts/utils/email_util.py"
    click Assets "https://github.com/ajil2545/auditbook-backend/blob/main/assets/red_book.xlsx"
    click Tests "https://github.com/ajil2545/auditbook-backend/blob/main/tests/test_api.py"
```
