# API Documentation This document provides detailed information about the API endpoints and functions available in the project. ## Main Application (`app.py`) This is the main entry point of the Flask application. It initializes the Flask app, registers blueprints, and sets up a test route. ### Blueprints The application is organized into the following blueprints: * **`auth_bp`**: Handles authentication-related routes. Mounted at `/auth`. * **`models_bp`**: Handles model-related routes. Mounted at `/models`. * **`gateway_bp`**: Acts as an API gateway. Mounted at `/gateway`. ### Endpoints #### `GET /api/test` A simple test endpoint to verify that the API is running. * **Method:** `GET` * **Response:** * **Success (200):** ```json { "success": true, "message": "GET API is working", "data": { "id": 1, "name": "Test User", "role": "Admin" } } ``` ## Database (`db.py`) This module provides a reusable function to get a database connection from the connection pool. ### Functions #### `get_db()` Returns a thread-safe instance of the MongoDB database connection. It uses the Flask application context (`g`) to store the connection and reuses it if it already exists for the current request. * **Returns:** A `pymongo.database.Database` instance. ## Configuration (`config.py`) This module loads database configuration from environment variables and creates a MongoDB client instance. ### Environment Variables The following environment variables are used to configure the database connection: * `MONGODB_USER_LIVE`: The username for the MongoDB database. * `MONGODB_PASSWORD_LIVE`: The password for the MongoDB database. * `MONGODB_HOST_LIVE`: The host of the MongoDB database. * `MONGODB_PORT_LIVE`: The port of the MongoDB database (defaults to `27017`). * `MONGODB_DB_LIVE`: The name of the MongoDB database. ### Functions #### `get_mongo_uri()` Constructs the MongoDB connection URI from the environment variables. * **Returns:** A string representing the MongoDB connection URI. ## Authentication (`auth/auth.py`) This module handles user authentication, including OTP generation and verification, user registration, and login. ### Endpoints #### `POST /v1/POSTverifyotp` Verifies the OTP sent to a user's phone number and creates a new user account. * **Method:** `POST` * **Request Body:** * `phone_number` (string, required): The user's phone number. * `country_code` (string, optional, default: `+91`): The user's country code. * `password` (string, required): The user's desired password. * `username` (string, required): The user's desired username. * `identifier` (string, required): The unique identifier for the OTP request. * `otp` (string, required): The OTP received by the user. * **Response:** * **Success (200):** ```json { "message": "OTP verified successfully, you may proceed", "code": 200, "res_data": { "user_id": "..." }, "status": "success" } ``` * **Error (4xx/5xx):** ```json { "message": "Error message", "code": "...", "res_data": {}, "status": "fail" } ``` #### `POST /v1/POSTloginsendotp` Sends an OTP to the user's phone number for login. * **Method:** `POST` * **Request Body:** * `phone_number` (string, required): The user's phone number. * `country_code` (string, optional, default: `+91`): The user's country code. * **Response:** * **Success (200):** ```json { "message": "OTP sent successfully", "code": 200, "res_data": { "identifier": "...", "type": "phone" }, "status": "success" } ``` * **Error (5xx):** ```json { "message": "Error message", "code": 500, "res_data": {}, "status": "fail" } ``` #### `POST /v1/POSTloginverifyotp` Verifies the OTP for login and creates or updates the user. * **Method:** `POST` * **Request Body:** * `identifier` (string, required): The OTP request identifier. * `otp` (string, required): The OTP. * `phone_number` (string, required): The user's phone number. * `country_code` (string, optional, default: `+91`): The user's country code. * `device_type` (string, optional): The user's device type. * `language` (string, optional, default: `en`): The user's preferred language. * **Response:** * **Success (200):** ```json { "message": "OTP verified successfully, you may proceed", "code": 200, "res_data": { "user_id": "...", "existing_user": "Y" or "N" }, "status": "success" } ``` * **Error (4xx/5xx):** ```json { "message": "Error message", "code": "...", "res_data": {}, "status": "fail" } ``` #### `POST /v1/register` Completes the user's profile after OTP verification. * **Method:** `POST` * **Request Body:** * `user_id` (string, required): The user's ID. * `username` (string, required): The user's username. * `city` (string, required): The user's city. * `state` (string, required): The user's state. * `profile_image` (string, optional): URL to the user's profile image. * `password` (string, required): The user's password. * `fcm_token` (string, optional): Firebase Cloud Messaging token. * `device_id` (string, optional): The user's device ID. * `device_version` (string, optional): The user's device version. * `device_name` (string, optional): The user's device name. * `latitude` (string, optional): The user's latitude. * `longitude` (string, optional): The user's longitude. * **Response:** * **Success (200):** ```json { "code": 200, "status": "success", "message": "Profile completed successfully", "res_data": { "user_id": "...", "username": "...", "fullname": "..." } } ``` * **Error (4xx/5xx):** ```json { "message": "Error message", "code": "...", "res_data": {}, "status": "error" } ``` #### `POST /v1/login` Logs in a user with their phone number and password or OTP. * **Method:** `POST` * **Request Body:** * `phone_number` (string, required): The user's phone number. * `auth_type` (string, required): `phone_password` or `phone_otp`. * `password` (string, optional): The user's password (if `auth_type` is `phone_password`). * `fcm_token` (string, optional): Firebase Cloud Messaging token. * `device_id` (string, optional): The user's device ID. * `device_type` (string, optional): The user's device type. * `latitude` (string, optional): The user's latitude. * `longitude` (string, optional): The user's longitude. * **Response:** * **Success (200):** ```json { "code": 200, "statusMessage": "success", "message": "Login successful.", "data": { "token": "...", "user": { "user_id": "...", "username": "...", "phone_number": "...", "is_profile_complete": "Y" or "N", "n_score_status": "..." } } } ``` * **Error (4xx/5xx):** ```json { "message": "Error message", "code": "...", "status": "error" } ``` #### `POST /v1/complete_profile` Completes a user's profile with additional details. * **Method:** `POST` * **Request Body:** * `user_id` (string, required): The user's ID. * `family_size` (integer, required): The user's family size. * `annual_income` (number, required): The user's annual income. * `business_location` (string, required): The user's business location. * `gender` (string, optional): The user's gender. * `marital_status` (string, optional): The user's marital status. * `working_members` (integer, optional): Number of working members in the family. * `no_of_child` (integer, optional): Number of children. * `current_city` (string, optional): The user's current city. * `current_pincode` (string, optional): The user's current pincode. * `current_address` (string, optional): The user's current address. * `permant_address` (string, optional): The user's permanent address. * `permant_city` (string, optional): The user's permanent city. * `permant_pincode` (string, optional): The user's permanent pincode. * `dob` (string, optional): The user's date of birth. * `address` (string, optional): The user's address. * `profile_pic` (string, optional): URL to the user's profile picture. * **Response:** * **Success (200):** ```json { "code": 200, "status": "success", "message": "Profile details saved successfully. Risk assessment queued.", "data": { "user_id": "...", "n_score_status": "PENDING" } } ``` * **Error (4xx/5xx):** ```json { "code": "...", "status": "fail" or "error", "message": "Error message", "data": {} } ``` #### `GET /api/roles` Retrieves all available user roles. * **Method:** `GET` * **Response:** * **Success (200):** ```json { "success": true, "message": "Roles fetched successfully", "data": [ { "_id": "...", "ROLE_NAME": "..." } ] } ``` * **Error (5xx):** ```json { "success": false, "message": "Error fetching roles", "error": "..." } ``` #### `POST /v1/intialize_loan` Initializes a new loan for a user. * **Method:** `POST` * **Request Body:** * `user_id` (string, required): The user's ID. * `amount_disbursed` (number, required): The amount of the loan disbursed. * `payback_amount` (number, required): The total amount to be paid back. * `purpose` (string, required): The purpose of the loan. * `initial_edi` (number, required): The initial EDI. * `type` (string, required): The type of the loan. * **Response:** * **Success (201):** ```json { "status": "success", "message": "Loan created successfully", "loan_id": "..." } ``` * **Error (4xx/5xx):** ```json { "status": "fail" or "error", "message": "Error message" } ``` #### `GET /v1/get_users_details/` Retrieves detailed information about a user, including KYC, loan, and n_score. * **Method:** `GET` * **URL Parameters:** * `user_id` (string, required): The ID of the user to retrieve. * **Response:** * **Success (200):** A JSON object containing the user's details. * **Error (404):** ```json { "success": false, "message": "User not found" } ``` #### `GET /v2/get_users_details/` Retrieves detailed information about a user (version 2). * **Method:** `GET` * **URL Parameters:** * `user_id` (string, required): The ID of the user to retrieve. * **Response:** * **Success (200):** A JSON object containing the user's details. * **Error (404):** ```json { "success": false, "message": "User not found" } ``` ## Models (`models/models.py`) This module contains functions for interacting with the database models. ### Functions #### `get_user_details(user_id, columns=None)` Fetches details for a specific user from the `user_master` collection. * **Parameters:** * `user_id` (string): The `ObjectId` of the user. * `columns` (list, optional): A list of specific fields (columns) to return. If `None`, all fields are returned. * **Returns:** * A JSON response object. * **Success (200):** ```json { "code": 200, "status": "success", "message": "User Details fetched Successfully", "data": { ... user data ... } } ``` * **Error (500):** ```json { "code": 500, "status": "fail", "message": "Error message or User not found", "data": {} } ``` ## Gateway (`gateway/forwarder.py` and `gateway/services.py`) This module acts as an API Gateway, forwarding requests to various downstream microservices. ### Endpoints #### `ANY //` Forwards incoming requests to the specified downstream service. * **Method:** `GET`, `POST`, `PUT`, `DELETE`, `PATCH` (any HTTP method) * **URL Parameters:** * `service` (string, required): The name of the target service (e.g., `kyc`, `lpm`, `leh`, `game`, `ads`). * `path` (string, required): The path within the target service's API. * **Request Headers:** All incoming headers are forwarded, except `host`. * **Request Query Parameters:** All incoming query parameters are forwarded. * **Request Body:** The raw request body is forwarded. * **Response:** The response from the downstream service is returned directly to the client, including its status code and headers (excluding `content-encoding` and `transfer-encoding`). * **Error (404):** ``` Service not found ``` If the specified `service` is not configured. * **Error (500):** ``` Error forwarding request ``` If an error occurs during the forwarding process (e.g., network issues, downstream service unavailable). ### Configuration The `gateway/services.py` file defines the mapping of service names to their respective base URLs using environment variables. * `SERVICES` (dictionary): * `kyc`: `GATEWAY_KYC_SERVICE` environment variable * `lpm`: `GATEWAY_LPM_SERVICE` environment variable * `leh`: `GATEWAY_LEH_SERVICE` environment variable * `game`: `GATEWAY_GAME_SERVICE` environment variable * `ads`: `GATEWAY_ADS_SERVICE` environment variable ## Extensions (`extensions/extensions.py`) This module initializes and configures Flask extensions used throughout the application. ### `mail` An instance of `flask_mail.Mail` for sending emails. ### `socketio` An instance of `flask_socketio.SocketIO` for handling WebSocket connections. * **Configuration:** * `cors_allowed_origins="*"`: Allows connections from any origin. * `async_mode='eventlet'`: Uses the eventlet asynchronous framework. * `logger=True`: Enables logging for Socket.IO events. * `engineio_logger=True`: Enables logging for the underlying Engine.IO transport.