# suryavaddiraju/irctc-api architecture

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

- Interactive diagram: https://gitdiagram.com/suryavaddiraju/irctc-api
- Repository: https://github.com/suryavaddiraju/irctc-api

## Overview

##### Project Type and Purpose
- This is a Node.js library (distributed as an npm package) that automates IRCTC ticket booking by wrapping IRCTC website APIs.
- Its main purpose is to simplify train ticket booking and user profile management on the Node.js platform, specifically for educational/demonstrative usage.
- It integrates external dependencies, like the “viu” binary, for handling captcha image display in terminal environments.

##### Analyzing the File Structure
- Top-Level Directories:
- .github: Contains community guidelines and GitHub workflow files such as CI/CD setups.
- docs: Holds documentation content, including API reference, configuration, and visual customizations for the documentation site.
- examples: Provides sample scripts (book.mjs, pnr_status.mjs, etc) that demonstrate how to use the library.
- lib: Contains the core library code. The ‘index.mjs’ exports the main IRCTC class along with other functions and variables. The ‘utils’ subdirectory holds helper functions (browsing, validation, handling external APIs like gcloud, etc).
- test: Shows sample tests for commands, ensuring functionalities like ticket booking.

##### Extracted Architectural Elements from the README
- Main Components:
- The IRCTC API wrapper: Exports the IRCTC class and its primary functions (book, last_transaction, pnr_status, master_passengers).
- Utility Functions: Organized into separate helper modules which support request handling (headers.mjs) and data manipulations (such as country, station handling, etc).
- External Dependency: “viu” (a Rust module) which is used to display captcha images on the command line.
- Operational Flow:
- Client applications import the IRCTC class from this package.
- The client creates a new instance with necessary IRCTC parameters.
- Then, using asynchronous calls (async/await pattern), the client executes one of the available operations (like book) that internally use the helper functions to communicate with IRCTC APIs.

a. Main Components:
- Client Application / Consumer: A Node.js script or application that uses the irctc-api package.
- IRCTC Library Core:
- IRCTC Class (from lib/index.mjs)
- Helper Modules (from lib/headers.mjs and lib/utils/*)
- External Services:
- IRCTC Website’s APIs (the actual endpoints being used behind the scenes)
- The “viu” binary for displaying captcha images.
- Supporting Layers:
- Testing code (from the test folder) to verify functionalities.
- Documentation (docs) and Examples (examples) that guide users.

b. Relationships & Interactions:
- The Client Application invokes operations on the IRCTC class.
- The IRCTC class internally utilizes the various helper methods from the utils modules to format requests, validate forms, or interact with additional APIs.
- When handling captcha verification, the code calls the “viu” binary (external dependency) to display images in the terminal.
- Asynchronous flows (using async/await) represent the interaction with external IRCTC APIs.

c. Important Architectural Patterns and Design Principles:
- Modularity: Separation of the core API (IRCTC class) from the utility functions. This improves code reuse and maintainability.
- Asynchronous programming: Leveraging async/await for cleaner promise handling.
- Integration of External Tools: Incorporating external binaries (viu) for improved user interaction in a command-line environment.

d. Technologies & Frameworks:
- Node.js as the runtime environment.
- JavaScript modules and the use of ES6+ syntax.
- GitHub Actions for CI/CD as seen in the .github/workflows directory.
- The use of npm for package distribution.
- The “viu” binary as an external dependency for image rendering.

- Client Application:
- IRCTC API Module:
- Main IRCTC class (lib/index.mjs) as the central processing hub.
- Utility modules (lib/headers.mjs and lib/utils) branching from it.
- External Services:
- IRCTC Website APIs.
- “viu” binary.
- Supporting Components:
- Testing suite (from tests) to show validation.
- Documentation and Examples directories as an aid for developers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Client (Node.js Application)"]:::client
    B["IRCTC API Wrapper"]:::core
    C["Utility: Headers Module"]:::utility
    D["Utility: Utils Modules"]:::utility
    E["Captcha Display (viu)"]:::external
    F["IRCTC Website APIs"]:::external
    G["Testing Suite"]:::support
    H["Documentation & API Reference"]:::support
    I["CI/CD & Community Guidelines"]:::support
    J["Examples"]:::support

    A -->|"invokes"| B
    B -->|"uses"| C
    B -->|"uses"| D
    D -->|"callsCaptcha"| E
    B -->|"callsAsync"| F
    B -.->|"testedBy"| G
    B -.->|"documentedIn"| H
    B -.->|"managedBy"| I
    A -.->|"exampleUsage"| J

    click B "https://github.com/suryavaddiraju/irctc-api/blob/main/lib/index.mjs"
    click C "https://github.com/suryavaddiraju/irctc-api/blob/main/lib/headers.mjs"
    click D "https://github.com/suryavaddiraju/irctc-api/tree/main/lib/utils/"
    click E "https://github.com/suryavaddiraju/irctc-api/blob/main/lib/utils/viu.mjs"
    click J "https://github.com/suryavaddiraju/irctc-api/tree/main/examples/"
    click G "https://github.com/suryavaddiraju/irctc-api/tree/main/test/"
    click H "https://github.com/suryavaddiraju/irctc-api/tree/main/docs/"
    click I "https://github.com/suryavaddiraju/irctc-api/tree/main/.github/"

    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef core fill:#D4EFDF,stroke:#145A32,stroke-width:2px;
    classDef utility fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef support fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
