openapi: 3.0.0
info:
  title: PROJ-microfinance_bank Engine API
  description: |
    Microfinance Banking Engine - Portal Integration with Finance Microservice
    Comprehensive financial services platform for microfinance operations.
    
    **Connected Microservices**:
    - auth-service (user authentication)
    - user-service (account management)
    - finance-service (financial operations, transactions, wallet management)
    
    **Database**: PROJ-microfinance_bank
    **Portal ID**: microfinance-engine
    **Version**: 1.0.0
  version: 1.0.0
  contact:
    name: Finance Operations Team
    email: operations@microfinance.local

servers:
  - url: http://localhost/projects/PROJ-microfinance_bank/frontend
    description: Development Microfinance Engine
  - url: https://finance.emmanylcode.local
    description: Production Microfinance Engine

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from auth-service

  schemas:
    Account:
      type: object
      properties:
        id:
          type: integer
          format: int64
        user_id:
          type: integer
        account_number:
          type: string
        account_type:
          type: string
          enum: [savings, checking, investment]
        balance:
          type: number
          format: float
        currency:
          type: string
          example: NGN
        status:
          type: string
          enum: [active, inactive, suspended]
        created_at:
          type: string
          format: date-time

    Transaction:
      type: object
      properties:
        id:
          type: integer
        account_id:
          type: integer
        type:
          type: string
          enum: [deposit, withdrawal, transfer, interest, loan_payment]
        amount:
          type: number
          format: float
        description:
          type: string
        balance_after:
          type: number
          format: float
        status:
          type: string
          enum: [pending, completed, failed, reversed]
        created_at:
          type: string
          format: date-time

    DepositRequest:
      type: object
      required:
        - account_id
        - amount
        - payment_method
      properties:
        account_id:
          type: integer
        amount:
          type: number
          format: float
          example: 50000.00
          description: Deposit amount (NGN)
        payment_method:
          type: string
          enum: [bank_transfer, card, mobile_money, cash]
        reference:
          type: string
          description: Payment reference or transaction ID

    WithdrawalRequest:
      type: object
      required:
        - account_id
        - amount
      properties:
        account_id:
          type: integer
        amount:
          type: number
          format: float
        withdrawal_method:
          type: string
          enum: [bank_transfer, cash]
        recipient_bank:
          type: string
        recipient_account:
          type: string

    LoanApplication:
      type: object
      properties:
        id:
          type: integer
        user_id:
          type: integer
        amount_requested:
          type: number
          format: float
        interest_rate:
          type: number
          format: float
        tenure_months:
          type: integer
        status:
          type: string
          enum: [pending, approved, rejected, active, completed]
        created_at:
          type: string
          format: date-time

    ApplyLoanRequest:
      type: object
      required:
        - amount_requested
        - tenure_months
      properties:
        amount_requested:
          type: number
          format: float
          example: 500000.00
        tenure_months:
          type: integer
          example: 12
        purpose:
          type: string
        collateral_value:
          type: number
          format: float

    SavingsGoal:
      type: object
      properties:
        id:
          type: integer
        user_id:
          type: integer
        name:
          type: string
        target_amount:
          type: number
          format: float
        current_amount:
          type: number
          format: float
        target_date:
          type: string
          format: date
        status:
          type: string
          enum: [active, completed, abandoned]

paths:
  /api/finance/accounts:
    get:
      summary: Get User Accounts
      description: Retrieve all financial accounts for the authenticated user
      operationId: getUserAccounts
      tags:
        - Accounts
      responses:
        '200':
          description: Accounts retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized

  /api/finance/accounts/{accountId}:
    get:
      summary: Get Account Details
      description: Retrieve detailed information about a specific account
      operationId: getAccountDetails
      tags:
        - Accounts
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Account details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          description: Account not found

  /api/finance/transactions/{accountId}:
    get:
      summary: Get Account Transactions
      description: Retrieve transaction history for an account
      operationId: getAccountTransactions
      tags:
        - Transactions
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: start_date
          in: query
          schema:
            type: string
            format: date
        - name: end_date
          in: query
          schema:
            type: string
            format: date
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Transactions retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Transaction'

  /api/finance/deposits:
    post:
      summary: Create Deposit
      description: Initiate a deposit transaction into an account
      operationId: createDeposit
      tags:
        - Deposits
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DepositRequest'
            examples:
              bankTransfer:
                summary: Bank Transfer Deposit
                value:
                  account_id: 1
                  amount: 50000.00
                  payment_method: bank_transfer
                  reference: TXN-2024-001
      responses:
        '201':
          description: Deposit initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  transaction:
                    $ref: '#/components/schemas/Transaction'
        '400':
          description: Validation error
        '401':
          description: Unauthorized

  /api/finance/withdrawals:
    post:
      summary: Create Withdrawal
      description: Initiate a withdrawal from an account
      operationId: createWithdrawal
      tags:
        - Withdrawals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WithdrawalRequest'
      responses:
        '201':
          description: Withdrawal initiated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  transaction:
                    $ref: '#/components/schemas/Transaction'
        '400':
          description: Validation error
        '401':
          description: Unauthorized

  /api/finance/loans:
    get:
      summary: Get User Loans
      description: Retrieve all loan applications and active loans
      operationId: getUserLoans
      tags:
        - Loans
      responses:
        '200':
          description: Loans retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LoanApplication'
        '401':
          description: Unauthorized

    post:
      summary: Apply for Loan
      description: Submit a new loan application
      operationId: applyForLoan
      tags:
        - Loans
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplyLoanRequest'
            examples:
              businessLoan:
                summary: Business Loan Application
                value:
                  amount_requested: 500000.00
                  tenure_months: 12
                  purpose: Business expansion
                  collateral_value: 600000.00
      responses:
        '201':
          description: Loan application submitted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  application:
                    $ref: '#/components/schemas/LoanApplication'
        '400':
          description: Validation error
        '401':
          description: Unauthorized

  /api/finance/savings-goals:
    get:
      summary: Get Savings Goals
      description: Retrieve all savings goals for the user
      operationId: getSavingsGoals
      tags:
        - Savings
      responses:
        '200':
          description: Savings goals retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SavingsGoal'

    post:
      summary: Create Savings Goal
      description: Create a new savings goal
      operationId: createSavingsGoal
      tags:
        - Savings
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - target_amount
                - target_date
              properties:
                name:
                  type: string
                target_amount:
                  type: number
                  format: float
                target_date:
                  type: string
                  format: date
      responses:
        '201':
          description: Savings goal created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavingsGoal'

  /api/finance/wallet:
    get:
      summary: Get Wallet Balance
      description: Retrieve current wallet balance and summary
      operationId: getWallet
      tags:
        - Wallet
      responses:
        '200':
          description: Wallet information retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_balance:
                    type: number
                    format: float
                  currency:
                    type: string
                  accounts:
                    type: array
                    items:
                      type: object
                      properties:
                        account_id:
                          type: integer
                        account_type:
                          type: string
                        balance:
                          type: number
                          format: float

  /api/finance/statements/{accountId}:
    get:
      summary: Get Account Statement
      description: Generate and retrieve account statement for a period
      operationId: getAccountStatement
      tags:
        - Reports
      parameters:
        - name: accountId
          in: path
          required: true
          schema:
            type: integer
        - name: month
          in: query
          schema:
            type: string
            example: "2024-05"
      responses:
        '200':
          description: Account statement retrieved
          content:
            application/pdf:
              schema:
                type: string
                format: binary

tags:
  - name: Accounts
    description: Account management endpoints
  - name: Transactions
    description: Transaction viewing endpoints
  - name: Deposits
    description: Deposit and funding endpoints
  - name: Withdrawals
    description: Withdrawal endpoints
  - name: Loans
    description: Loan application and management
  - name: Savings
    description: Savings goal management
  - name: Wallet
    description: Wallet and balance endpoints
  - name: Reports
    description: Financial reports and statements
