# cnlnn/ja3-server architecture

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

- Interactive diagram: https://gitdiagram.com/cnlnn/ja3-server
- Repository: https://github.com/cnlnn/ja3-server

## Overview

##### Project type and purpose
- This is a lightweight Python microservice whose sole responsibility is to listen for incoming TLS connections, extract the JA3 fingerprint from each client’s TLS ClientHello, and (optionally) log it.
- There is no frontend, no database, and no persistent storage beyond console or file‐based logs. It’s effectively a single‐component, single‐responsibility network service.

##### File structure
- Top-level files only:
- README.md – usage instructions and description
- ja3-server.py – the whole server implementation
- server.crt & server.key – TLS certificate and private key
- No additional modules, libraries or subdirectories. The script probably uses Python’s built‐in libraries (socket, ssl, argparse).

##### README for additional insights
- Default behavior: listen on 127.0.0.1:443, no logs
- Flags: “-l” to set bind address and port, “-v” to turn on verbose logging
- Example screenshot shows JA3 hash output via curl test

##### Main components
a. External Client(s) (e.g., curl, browsers, custom TLS client)
b. Network and TLS handshake layer
c. Python ja3-server.py service
– CLI/argparse component (parsing “-l” and “-v”)
– SSLContext/ssl.wrap_socket for server.crt & server.key
– JA3 fingerprint extraction logic
– Logging mechanism (console or file, verbose vs. silent)
d. (Optional) Log sink (stdout, file, syslog)

##### Architectural patterns & design principles
- Single‐responsibility, microservice‐style design
- CLI flag‐driven configuration
- Use of standard library modules only (socket, ssl, argparse)
- Event‐driven (accept → handle → loop)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    ExternalClient["External Client"]:::external
    UsageDoc["Usage Documentation (README.md)"]:::external

    %% JA3 Server Subgraph
    subgraph "JA3 Server (ja3-server.py)"
        direction TB
        CLIParser["CLI/Argparse"]:::core
        SSLContext["SSLContext Loader"]:::config
        ConfigCert["server.crt"]:::config
        ConfigKey["server.key"]:::config
        JA3Extractor["JA3 Extraction Logic"]:::core
        Logger["Logging Mechanism"]:::log
    end

    %% Log Sink
    LogSink["Log Sink (Console/File)"]:::log

    %% Connections
    ExternalClient -->|"TCP/TLS ClientHello"| SSLContext
    SSLContext -->|"Loads Cert/Key"| ConfigCert
    SSLContext -->|"Loads Cert/Key"| ConfigKey
    SSLContext -->|"Handshake data"| JA3Extractor
    JA3Extractor -->|"JA3 fingerprint"| Logger
    Logger -->|"Log output"| LogSink

    %% Click Events
    click CLIParser "https://github.com/cnlnn/ja3-server/blob/main/ja3-server.py"
    click SSLContext "https://github.com/cnlnn/ja3-server/blob/main/ja3-server.py"
    click ConfigCert "https://github.com/cnlnn/ja3-server/blob/main/server.crt"
    click ConfigKey "https://github.com/cnlnn/ja3-server/blob/main/server.key"
    click JA3Extractor "https://github.com/cnlnn/ja3-server/blob/main/ja3-server.py"
    click Logger "https://github.com/cnlnn/ja3-server/blob/main/ja3-server.py"
    click UsageDoc "https://github.com/cnlnn/ja3-server/blob/main/README.md"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#000000,color:#000000;
    classDef core fill:#90EE90,stroke:#000000,color:#000000;
    classDef config fill:#FFD700,stroke:#000000,color:#000000;
    classDef log fill:#D3D3D3,stroke:#000000,color:#000000;
```
