---
title: SAIF.Framework.Common.Files overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-15
library: SAIF.Framework.Common.Files
reference_type: package
---

# SAIF.Framework.Common.Files overview

> **Documentation context:** Packaged Component (NuGet)

`SAIF.Framework.Common.Files` is a .NET Framework 4.6.2 class library (root namespace `SAIF.Common.Files`) published as the NuGet package `SAIF.Framework.Common.Files`. It bundles two independent capabilities behind a single assembly: a declarative flat-file reader/writer and an ASC X12 EDI object model, both built on the same-repo `SAIF.Framework.Common` utility package.

## Purpose
- Read and write delimited (CSV, tab-delimited, custom-delimiter) and fixed-width flat files by mapping rows to POCO record types through class/property attributes or a fluent, code-first configuration API.
- Model, parse, build, and serialise ASC X12 EDI interchange files — the envelope hierarchy (interchange → functional group → transaction set → hierarchical transaction → hierarchical level) plus roughly 40 strongly-typed segment classes covering 837 claim, 835 remittance, 277 claim status, and 997/999 acknowledgement healthcare transactions*.
- Consuming applications choose the subsystem they need; the flat-file engine and the EDI engine share only the minimal `IParser<T>` contract and the delegated `SAIF.Framework.Common` utilities, so either can be used without the other.

## Responsibilities
- Discover per-record-type file layout from declarative attributes (`Csv`, `TabDelimited`, `DelimitedBy`, `FixedFormat`, `DelimitedLayout`, `FixedLayout`) or a fluent `FileConfiguration<T>` subclass, then read/write records accordingly (`FileReader<TRecord>`, `FileWriter<TRecord>`).
- Parse raw EDI text into a segment/element object model (`EdiSegmentParser` → `EdiDataElementParser` → `EdiCompositeDataElementParser`) and reconstitute the X12 envelope hierarchy from a flat segment list (`EdiGroupParser`).
- Build and serialise EDI segments from typed objects (`SegmentBuilder`, `EdiRecordBuilder`) and provide ~43 typed segment classes (`Edi\Segments\*`) implementing a uniform `Build()`/`Fill()`/`Parse()` pattern.
- Provide file-system IO for both subsystems (`Core\FileReader`/`FileWriter`, `Edi\Core\Readers\EdiFileReader`, `Edi\Core\Writers\EdiFileWriter`), with no database, configuration, or network dependency.

## Key components
- `FileReader<TRecord>` / `FileWriter<TRecord>`: attribute- and configuration-driven typed flat-file IO engine.
- `FileConfiguration<T>` / `FileLayoutBuilder`: fluent, code-first alternative to attribute-based layout declaration.
- `EdiManager` / `EdiFileBuilder`: sanctioned facade for reading and writing EDI interchange files.
- `EdiGroupParser`: converts a flat segment list into the X12 envelope hierarchy (functional groups, transaction sets, hierarchical transactions and levels).
- `SegmentBuilder` / `EdiRecordBuilder`: element-ordering and text-serialisation engine used by every typed segment's `Build()`.
- `Edi\Segments\*`: ~43 typed segment classes (`IsaSegment`, `GsSegment`, `StSegment`, `ClpSegment`, `SvcSegment`, `TrnSegment`, and others) mapping typed properties to X12 segment elements.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts.

## Sources
- Common\SAIF.Common.Files\SAIF.Framework.Common.Files.csproj
- Common\SAIF.Common.Files\SAIF.Framework.Common.Files.nuspec
- Common\SAIF.Common.Files\IParser.cs
- Common\SAIF.Common.Files\Core\FileReader.cs
- Common\SAIF.Common.Files\Core\FileWriter.cs
- Common\SAIF.Common.Files\Edi\EdiManager.cs
- Common\SAIF.Common.Files\Edi\Core\Parsers\EdiGroupParser.cs
- Common\SAIF.Common.Files\Edi\Core\Builders\SegmentBuilder.cs
- Common\SAIF.Common.Files\Edi\Core\Builders\EdiRecordBuilder.cs