# aj-authify/api architecture

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

- Interactive diagram: https://gitdiagram.com/aj-authify/api
- Repository: https://github.com/aj-authify/api

## Overview

Step 1: Project Type and Purpose
- The project is an API service called "Authify API" built on FastAPI, designed to manage phone number-based authentication by generating and verifying TPO (temporary passcode) codes.
- It uses MongoDB for secure data storage and includes endpoints for generating and verifying TPOs.

Step 2: Analyze the File Structure
- Top-level files and directories:
- main.py: Likely the FastAPI application entry point.
- README.md: Provides an overview of the API endpoints and functionalities.
- requirements.txt and Procfile: Indicate dependencies and deployment (likely on Azure or similar cloud).
- Key directories/modules:
- mongodb: Contains the initialization and setup code for MongoDB, managing data persistence.
- phone_number: Handles validation logic for phone numbers.
- tpo: Contains modules for generating, verifying, and validating temporary passcodes (TPO codes).
- verifier: Includes modules that verify the correctness of phone numbers, TPOs, and website credentials.
- website: Includes modules for validating website input.
- The .github directory shows CI/CD workflows used possibly for automated testing or deployments.

Step 3: Insights from the README
- The README clearly defines two POST endpoints:
- /tpo/generate for generating TPO codes.
- /tpo/verify for validating TPO codes.
- It also outlines the core features such as validation for phone numbers and websites, and secure storage using MongoDB.
- The architecture suggests that the business logic is well-separated into modules (phone_number, tpo, verifier, website) for a modular design.

a. Main Components to Include:
- FastAPI Web Server (main.py): The entry point for handling HTTP requests.
- API Endpoints:
- Endpoint for generating TPO (/tpo/generate)
- Endpoint for verifying TPO (/tpo/verify)
- Business Logic/Modules:
- TPO Module: tpo/new_tpo.py, tpo/exist_tpo.py, tpo/valid_tpo.py, tpo/verify_tpo.py for generating and checking codes.
- Phone Number Module: phone_number/valid_phone_number.py handles validation of phone numbers.
- Website Module: website/valid_website.py ensuring the website input format is correct.
- Verifier Module: verifier/phone_number_verifier.py, verifier/tpo_verifier.py, verifier/website_verifier.py enforce proper verification logic.
- Data Storage:
- MongoDB Module: mongodb/setup.py sets up and manages secure storage of data.
- CI/CD Pipeline:
- .github/workflows: For automated tests and deployments.

b. Relationships and Interactions:
- The FastAPI server receives HTTP requests which are routed to appropriate endpoint handlers in main.py.
- On receiving a request at /tpo/generate, the server uses the TPO module to create a temporary passcode and validates phone number and website inputs via the phone_number and website modules.
- The TPO code and necessary details are stored in MongoDB as the persistent data layer.
- For /tpo/verify, the API routes the request to use verifier modules (including phone_number_verifier, tpo_verifier, and website_verifier) to confirm input validity and correctness with MongoDB data.
- CI/CD workflows automatically test and deploy these components.

c. Architectural Patterns and Design Principles:
- Modular design: Each feature (TPO generation, phone number/website validation, verification logic) is separated into its own module.
- Separation of concerns: Database operations, input validation, and authentication are clearly segmented, making the solution extensible.
- API-centric design: FastAPI as a framework promotes clear separation between request handling and business logic.

d. Relevant Technologies:
- FastAPI for building the API.
- MongoDB for data persistence.
- Python libraries for validation and business logic.
- CI/CD tools such as GitHub Actions for deployment and automated testing (see .github/workflows).

- The API layer (FastAPI application) that separates endpoint routing.
- The business logic modules that process and validate the inputs.
- The MongoDB layer as the core data store.
- How input flows through validation modules before any database operations.

- Use clear labels for each component – for example, “FastAPI Server (main.py)”, “TPO Generation Module”, “Validation Modules (phone_number, website)”, “Verification Modules”, and “MongoDB Data Store”.
- From the API endpoints (incoming HTTP requests) to the respective business logic modules.
- From business logic modules to the MongoDB storage component.
- Interaction between different validation and verification modules.
- API components (e.g., rectangles for endpoints),

Step 7: Detailed Architectural Elements Capturing
- Be detailed and capture both the high-level overview and individual interactions:
- Clearly separate components like FastAPI, TPO generation, verification logic, and storage.
- Every module from the file tree to ensure all significant interactions — especially the chain from input validation to MongoDB storage in generating and verifying TPOs — are identified.

Final Instruction for Principal Software Engineer:

Happy Diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        API["FastAPI Server (main.py)"]:::api
        GEN_EP["POST /tpo/generate"]:::endpoint
        VERIFY_EP["POST /tpo/verify"]:::endpoint
        API --> GEN_EP
        API --> VERIFY_EP
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        %% TPO Modules Subgraph
        subgraph "TPO Modules"
            TPO_New["TPO Creation (tpo/new_tpo.py)"]:::tpo
            TPO_Exist["TPO Existence Check (tpo/exist_tpo.py)"]:::tpo
            TPO_Valid["TPO Validation (tpo/valid_tpo.py)"]:::tpo
            TPO_Verify["TPO Verification (tpo/verify_tpo.py)"]:::tpo
            TPO_New --> TPO_Exist
            TPO_Exist --> TPO_Valid
            TPO_Valid --> TPO_Verify
        end
        PhoneVal["Phone Number Validation (phone_number/valid_phone_number.py)"]:::validation
        WebVal["Website Validation (website/valid_website.py)"]:::validation

        subgraph "Verifier Modules"
            PhoneVer["Phone Verification (verifier/phone_number_verifier.py)"]:::verifier
            TPOVer["TPO Verification (verifier/tpo_verifier.py)"]:::verifier
            WebVer["Website Verification (verifier/website_verifier.py)"]:::verifier
        end
    end

    %% Data Storage Layer
    subgraph "Data Storage"
        MongoDB["MongoDB Data Storage (mongodb/setup.py)"]:::database
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        CICD["CI/CD (GitHub Actions) (.github/workflows/main_authify-api.yml)"]:::cicd
    end

    %% Connections for TPO Generation flow
    GEN_EP --> PhoneVal
    GEN_EP --> WebVal
    PhoneVal --> TPO_New
    WebVal --> TPO_New
    TPO_Verify --> MongoDB

    %% Connections for TPO Verification flow
    VERIFY_EP --> PhoneVer
    VERIFY_EP --> TPOVer
    VERIFY_EP --> WebVer
    PhoneVer --> MongoDB
    TPOVer --> MongoDB
    WebVer --> MongoDB

    %% Styles
    classDef api fill:#b3d9ff,stroke:#333,stroke-width:2px;
    classDef endpoint fill:#d9e6ff,stroke:#333,stroke-width:2px;
    classDef tpo fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef validation fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef verifier fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef database fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef cicd fill:#e6ccff,stroke:#333,stroke-width:2px;

    %% Click Events
    click API "https://github.com/aj-authify/api/blob/main/main.py"
    click MongoDB "https://github.com/aj-authify/api/blob/main/mongodb/setup.py"
    click PhoneVal "https://github.com/aj-authify/api/blob/main/phone_number/valid_phone_number.py"
    click TPO_New "https://github.com/aj-authify/api/blob/main/tpo/new_tpo.py"
    click TPO_Exist "https://github.com/aj-authify/api/blob/main/tpo/exist_tpo.py"
    click TPO_Valid "https://github.com/aj-authify/api/blob/main/tpo/valid_tpo.py"
    click TPO_Verify "https://github.com/aj-authify/api/blob/main/tpo/verify_tpo.py"
    click PhoneVer "https://github.com/aj-authify/api/blob/main/verifier/phone_number_verifier.py"
    click TPOVer "https://github.com/aj-authify/api/blob/main/verifier/tpo_verifier.py"
    click WebVer "https://github.com/aj-authify/api/blob/main/verifier/website_verifier.py"
    click WebVal "https://github.com/aj-authify/api/blob/main/website/valid_website.py"
    click CICD "https://github.com/aj-authify/api/blob/main/.github/workflows/main_authify-api.yml"
```
