# rakshithvk19/rax-ftp-server architecture

> Architecture diagram of the GitHub repository rakshithvk19/rax-ftp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rakshithvk19/rax-ftp-server
- Repository: https://github.com/rakshithvk19/rax-ftp-server

## Overview

##### Project type and purpose
- This is a systems-level, networked FTP server written in Rust, implementing core RFC 959 commands. It’s not a front-end/backend web app but an open-source command-line server demonstrating TCP networking, multi-threading, modular design, and Rust skills.

##### File structure
- Top-level:
- src/main.rs – application entrypoint, logging setup, starts the server
- src/server.rs – listens on TCP port 2121, accepts control connections, spawns client threads
- src/client.rs & src/client_handler.rs – per-client state (authenticated user, CWD, data ports) and thread logic
- src/commands/ – parser.rs (parses raw FTP commands), handlers.rs (executes them), utils.rs (shared helpers)
- src/data_channel.rs – establishes active (PORT) or passive (PASV) data connections
- src/file_transfer.rs – implements STOR, RETR, LIST over data channels
- src/auth.rs – USER/PASS/LOGOUT logic
- src/utils.rs – common helpers (e.g., IP validation, path normalization)
- tests/integration.rs – end-to-end command parsing and server behavior

##### Readme insights
- The README confirms: single control listener, multi-threaded client handling via std::thread + Arc<Mutex<HashMap>> for shared client tracking, logging via `log`/`env_logger`, and core FTP commands (STOR, RETR, LIST, CWD, PWD, etc.)

##### Main components
a. Control Connection Listener
- TCP Listener on 127.0.0.1:2121 (src/server.rs)
b. Thread Manager / Client Thread
- On accept, spawn a thread, wrap shared state in Arc<Mutex<HashMap<ClientID,ClientState>>>
- Instantiate ClientHandler (src/client_handler.rs) to manage session
c. Authentication Module (src/auth.rs)
- Handles USER, PASS, LOGOUT, updates ClientState
d. Command Parser (src/commands/parser.rs)
- Parses incoming lines into FTPCommand enums
e. Command Handlers (src/commands/handlers.rs)
- Routes commands to auth, file transfer, directory management, session management
f. Data Channel Manager (src/data_channel.rs)
- Active (PORT) & Passive (PASV) modes: negotiates and opens data sockets
g. File Transfer Module (src/file_transfer.rs)
- Implements STOR, RETR, LIST, reading/writing local filesystem
h. Directory Navigation (via handlers + utils.rs)
- CWD, PWD, validating paths
i. Shared ClientState Store
- Arc<Mutex<HashMap>> tracking each client’s IP, auth status, working dir, data port
j. Logging Subsystem
- log crate + env_logger: logs command receipt, transfers, errors

##### Relationships and interactions
- External FTP Client → TCP 2121 → Server Listener
- Listener → spawns Thread → ClientHandler
- ClientHandler loops: read TCP control → Parser → Command Handler
- Handler may call Auth, Data Channel, File Transfer, Directory modules
- Data operations open secondary TCP sockets → transfer with client
- All modules write to shared ClientState and to logs

##### Architectural patterns & design principles
- Modular separation: auth, parser, handlers, data, transfer
- Multi-threading with shared Mutex state for concurrency control
- Single responsibility per module, clear crate boundaries
- Synchronous/blocking I/O (std::net, std::thread), clear future async scope

##### Technologies, frameworks, libraries
- Rust 2021 edition, Cargo
- std::net::TcpListener / TcpStream
- std::thread, std::sync::{Arc,Mutex}
- log + env_logger for tracing
- telnet / netcat only for testing

##### Essential elements
- Shared state store with mutex annotation
- Logging subsystem as a side component that all modules call into

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["External FTP Client"]:::external

    %% Server Core
    subgraph "Server Core"
        Main["Application Entrypoint & Logging Setup"]:::session
        Listener["Control Connection Listener\n(TCP 127.0.0.1:2121)"]:::net
    end

    %% Session Manager
    subgraph "Session Manager"
        Thread["Thread Manager / Client Thread Logic"]:::session
        StateDef["Per-Client State Definition"]:::session
        SharedState["Shared ClientState Store\n(Arc<Mutex<HashMap>>)",]:::session
        Auth["Authentication Module"]:::session
    end

    %% Protocol Layer
    subgraph "Protocol Layer"
        Parser["Command Parser"]:::protocol
        Handlers["Command Handlers"]:::protocol
        CmdUtils["Command Utilities"]:::protocol
    end

    %% Data Layer
    subgraph "Data Layer"
        DataChan["Data Channel Manager\n(PORT & PASV)"]:::data
        FileTrans["File Transfer Module\n(STOR/RETR/LIST)"]:::data
        Utils["Common Utilities\n(path normalization, IP validation)"]:::util
    end

    %% Shared Components
    subgraph "Project Artifacts"
        Lib["Shared Library Initialization"]:::util
        Cargo["Cargo Configuration & Dependencies"]:::util
        Readme["Project README & High-Level Docs"]:::util
        Tests["Integration Tests\n(end-to-end)"]:::util
    end

    %% Logging as side component
    subgraph "Logging Subsystem"
        Logging["log + env_logger"]:::util
    end

    %% Connections
    Client -->|"TCP 2121"| Listener
    Main --> Listener
    Main --> Logging
    Listener -->|"spawn thread"| Thread
    Thread --> StateDef
    Thread --> SharedState
    Thread --> Parser
    Parser -->|"FTP command"| Handlers
    Handlers --> Auth
    Handlers --> DataChan
    Handlers --> FileTrans
    Handlers --> CmdUtils
    Handlers --> StateDef
    DataChan --> FileTrans
    FileTrans -->|"data over TCP"| Client
    Auth --> SharedState
    Thread --> Logging
    Parser --> Logging
    Handlers --> Logging
    DataChan --> Logging
    FileTrans --> Logging
    Utils --> DataChan
    Utils --> FileTrans

    %% Project Artifacts connectivity
    Lib --> Main
    Cargo --> Main
    Readme --> Main
    Tests --> Handlers

    %% Click Events
    click Listener "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/server.rs"
    click Main "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/main.rs"
    click Thread "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/client_handler.rs"
    click StateDef "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/client.rs"
    click Auth "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/auth.rs"
    click Parser "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/commands/parser.rs"
    click Handlers "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/commands/handlers.rs"
    click CmdUtils "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/commands/utils.rs"
    click DataChan "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/data_channel.rs"
    click FileTrans "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/file_transfer.rs"
    click Utils "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/utils.rs"
    click Lib "https://github.com/rakshithvk19/rax-ftp-server/blob/main/src/lib.rs"
    click Tests "https://github.com/rakshithvk19/rax-ftp-server/blob/main/tests/integration.rs"
    click Cargo "https://github.com/rakshithvk19/rax-ftp-server/blob/main/Cargo.toml"
    click Readme "https://github.com/rakshithvk19/rax-ftp-server/blob/main/README.md"

    %% Styles
    classDef net fill:#a8f0a8,stroke:#008000,color:#000;
    classDef session fill:#a8d0f0,stroke:#004080,color:#000;
    classDef protocol fill:#f0e68c,stroke:#808000,color:#000;
    classDef data fill:#f0b27a,stroke:#c04d00,color:#000;
    classDef util fill:#d0a0f0,stroke:#600080,color:#000;
    classDef external fill:#cccccc,stroke:#666666,color:#000;
```
