# osiegmar/fastcsv architecture

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

- Interactive diagram: https://gitdiagram.com/osiegmar/fastcsv
- Repository: https://github.com/osiegmar/fastcsv

## Overview

##### Project type and purpose
- FastCSV is an open-source, dependency‐free CSV library for Java.
- It provides both reader and writer APIs, adheres to RFC standards, and includes examples, benchmarks, tests, and a documentation site.

##### File structure
- Top-level modules:
- buildSrc/ + gradle wrappers and version catalogs – custom build logic & dependency management
- lib/ – the multi‐module Gradle project containing:
– main/java/… – core CSV reader, writer, util code
– test/java/… – unit tests
– jmh/java – microbenchmarks for read/write performance
- example/ – standalone sample app demonstrating library usage
- docs/ – static site (Astro, MDX) hosting guides, architecture docs, quickstarts
- .github/workflows – CI/CD pipelines (build, test, code analysis, release)
- Configuration files for Checkstyle, PMD, SpotBugs enforce quality rules.

##### README insights
- Confirms project is a high-performance CSV library.
- Points to website and badges for Javadoc, CI, code coverage, fuzzing, best practices.

##### Main components & interactions
a. Core Library
- Reader package: CsvReader, CsvParser, CsvCallbackHandler, BOM handling
- Writer package: CsvWriter, QuoteStrategy, buffered/unbuffered writers
- Util package: Preconditions, Limits, helper classes
b. Build System & CI
- Gradle build orchestrates compilation, testing, benchmarks, packaging, publishing
- GitHub Actions run build.yml, codeql, dependency management, deploy docs, publish JARs to Maven Central
c. Testing & Benchmarking
- JUnit for unit and integration tests
- JMH for performance benchmarks
d. Documentation & Examples
- Astro-based docs site deployed via CI
- example/ project imports the library artifact to demonstrate usage
e. External Services
- Maven Central (artifact publication)
- Javadoc.io (API docs)
- OSS-Fuzz, Codecov, Codacy (quality and coverage)

##### Architectural patterns & design principles
- Modular multi-project Gradle setup (separation: core code, tests, benchmarks, examples, docs)
- Clear API boundaries: reader vs writer vs util
- Extension points via handler interfaces (CsvCallbackHandler, FieldModifier)
- No third-party dependencies – encourages zero-overhead integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer triggering CI
    Developer["Developer"]:::ext
    Developer -->|"push code"| GitHubActions

    %% CI/CD Pipelines
    subgraph "CI/CD Pipelines"
        direction TB
        BuildYML["build.yml"]:::ci
        CodeQL["codeql-analysis.yml"]:::ci
        Dependency["dependency-submission.yml"]:::ci
        Deploy["deploy.yml"]:::ci
        Release["release.yml"]:::ci
    end
    GitHubActions["GitHub Actions"]:::ci
    Developer --> GitHubActions
    GitHubActions -->|"runs workflows"| BuildYML
    GitHubActions --> CodeQL
    GitHubActions --> Dependency
    GitHubActions --> Deploy
    GitHubActions --> Release

    %% Build System
    subgraph "Build System (Gradle)" 
        direction TB
        BuildSrc["buildSrc/"]:::build
        VersionCatalog["libs.versions.toml"]:::build
        Wrapper["wrapper/"]:::build
    end
    GitHubActions -->|"invoke gradle"| Gradle
    Gradle["Gradle Build"]:::build
    Gradle --> BuildSrc
    Gradle --> VersionCatalog
    Gradle --> Wrapper

    %% Core Library
    subgraph "Core Library" 
        direction TB
        Reader["Reader Module"]:::core
        Writer["Writer Module"]:::core
        Util["Util Module"]:::core
    end
    Gradle -->|"compile core"| Reader
    Gradle --> Writer
    Gradle --> Util

    %% Testing
    subgraph "Testing"
        direction TB
        UnitTests["Unit Tests"]:::test
        TestUtils["Test Utilities"]:::test
        IntTests["Integration Tests"]:::test
    end
    Gradle -->|"run tests"| UnitTests
    Gradle --> TestUtils
    Gradle --> IntTests

    %% Benchmarking
    subgraph "Benchmarking"
        direction TB
        JMH["JMH Benchmarks"]:::test
    end
    Gradle -->|"run benchmarks"| JMH

    %% Documentation & Example
    subgraph "Docs & Example"
        direction TB
        Docs["Documentation Site"]:::doc
        ExampleApp["Example Application"]:::doc
    end
    GitHubActions -->|"deploy docs"| Docs
    Docs -->|"consume artifact"| MavenCentral
    ExampleApp -->|"consume artifact"| MavenCentral

    %% Artifact Publication
    MavenCentral["Maven Central"]:::ext
    JavadocIO["Javadoc.io"]:::ext
    Codecov["Codecov"]:::ext
    Codacy["Codacy"]:::ext
    OSSFuzz["OSS-Fuzz"]:::ext

    Release -->|"publish jar"| MavenCentral
    Deploy -->|"deploy site"| JavadocIO
    CodeQL -->|"fuzzing"| OSSFuzz
    BuildYML -->|"coverage reports"| Codecov
    BuildYML -->|"quality badges"| Codacy

    %% Relationships
    Gradle -->|"package jar"| MavenCentral

    %% Click Events
    click Reader "https://github.com/osiegmar/fastcsv/tree/main/lib/src/main/java/de/siegmar/fastcsv/reader"
    click Writer "https://github.com/osiegmar/fastcsv/tree/main/lib/src/main/java/de/siegmar/fastcsv/writer"
    click Util "https://github.com/osiegmar/fastcsv/tree/main/lib/src/main/java/de/siegmar/fastcsv/util"
    click BuildSrc "https://github.com/osiegmar/fastcsv/tree/main/buildSrc/"
    click VersionCatalog "https://github.com/osiegmar/fastcsv/blob/main/gradle/libs.versions.toml"
    click Wrapper "https://github.com/osiegmar/fastcsv/tree/main/gradle/wrapper/"
    click BuildYML "https://github.com/osiegmar/fastcsv/blob/main/.github/workflows/build.yml"
    click CodeQL "https://github.com/osiegmar/fastcsv/blob/main/.github/workflows/codeql-analysis.yml"
    click Dependency "https://github.com/osiegmar/fastcsv/blob/main/.github/workflows/dependency-submission.yml"
    click Deploy "https://github.com/osiegmar/fastcsv/blob/main/.github/workflows/deploy.yml"
    click Release "https://github.com/osiegmar/fastcsv/blob/main/.github/workflows/release.yml"
    click UnitTests "https://github.com/osiegmar/fastcsv/tree/main/lib/src/test/java/de/siegmar/fastcsv"
    click TestUtils "https://github.com/osiegmar/fastcsv/tree/main/lib/src/common/java/testutil"
    click IntTests "https://github.com/osiegmar/fastcsv/tree/main/lib/src/intTest/java"
    click JMH "https://github.com/osiegmar/fastcsv/tree/main/lib/src/jmh/java/de/siegmar/fastcsv"
    click Docs "https://github.com/osiegmar/fastcsv/tree/main/docs/"
    click ExampleApp "https://github.com/osiegmar/fastcsv/tree/main/example/"

    %% Styles
    classDef core fill:#ffe4e1,stroke:#333,stroke-width:1px
    classDef build fill:#e6f7ff,stroke:#333,stroke-width:1px
    classDef ci fill:#e2ffe6,stroke:#333,stroke-width:1px
    classDef test fill:#fff0f5,stroke:#333,stroke-width:1px
    classDef doc fill:#fffacd,stroke:#333,stroke-width:1px
    classDef ext fill:#f0f8ff,stroke:#333,stroke-width:1px
```
