1. Parser-Centered Architecture

The useful mental model is simple: the parser reads X12, builds the interchange graph, and gives you the structures that validation, acknowledgements, and downstream consumers depend on.

• Parsing core: object model, schema loading, parsing flow, validation, ACK generation.
• Parser helpers: split, batch, and object traversal support built on parsed interchanges.
• Everything else: downstream or surrounding layers that should stay secondary.

When documenting or extending the solution, keep that hierarchy visible. The parser should remain the primary narrative.

2. Parser Core

HIPAAsuite.AuroraParser contains the domain model and the parser-facing workflow. The important building blocks are:

• CommonEDIHandler builds the interchange graph while segments stream in.
• LazyParserLite is the usual entry point for parsing files and strings.
• APFFactory and related APF assets provide schema definitions for supported transaction sets.
• Validator attaches validation logic to parsed interchanges.
• FileSplitter supports transaction-set level output restructuring after parsing.

using AuroraParser;
using HIPAAsuite.Data;

using var handler = new CommonEDIHandler();
using var parser = new LazyParserLite(handler);

parser.Parse("claim.edi");

foreach (var interchange in handler.Interchanges)
{
    Console.WriteLine(interchange.ISA?.InterchangeControlNumber);
}

3. Startup and Initialization

Runtime initialization matters because the parser depends on schemas and, for deeper validation, code-set data. Load those assets at application startup and keep them versioned with intent.

using HIPAAsuite.AuroraParser;
using HIPAAsuite.AuroraParser.CodeSets;

APFFactory.Initialize(APFFileEnum.Claim_5010x222A1);
APFFactory.Initialize(APFFileEnum.Payment_5010x221A1);

CsvLoader.Instance.StartLoading(new Dictionary<string, CsvLoader.CsvLoadRequest>
{
    { CsvFileEnum.States.ToString(), new CsvLoader.CsvLoadRequest(1, hasHeader: false) }
});

await CsvLoader.Instance.WaitUntilLoadedAsync();

4. Parsed Object Model

The central traversal model is simple and worth keeping simple in the docs: interchange, then functional groups, then transaction sets, then segments.

foreach (var interchange in handler.Interchanges)
{
    foreach (var group in interchange.FunctionalGroups)
    {
        foreach (var transactionSet in group.TransactionSets)
        {
            foreach (var segment in transactionSet.Segments)
            {
                Console.WriteLine(segment.SegmentStandard?.ID);
            }
        }
    }
}

That graph is the main contract most applications should depend on.

5. Validation and Acknowledgements

Validation and ACK generation are parser-adjacent responsibilities because they operate directly on the interchange graph and its control-number structure.

foreach (var interchange in handler.Interchanges)
{
    var validator = Validator.GetValidator(interchange);
    validator.ValidateInterchange();
}

var ack999 = handler.Generate999();
File.WriteAllText("999.edi", ack999.ToEdiString());

Keep delivery of the ACK separate from generation of the ACK. The first is transport; the second is parser workflow.

6. Serialization from Parsed Interchanges

Many applications want JSON output right after parsing. Keep that concern downstream of the parser and treat the parsed interchange graph as the source of truth.

using HIPAAsuite.AuroraObjectsTransformers;
using Newtonsoft.Json;

var json = JsonConvert.SerializeObject(
    handler.Interchanges,
    new InterchangeListJsonConverter(includeMetadata: true, namingConvention: NamingConvention.CamelCase)
);

Serialization is useful, but it is still downstream of the parser rather than a peer to it.

7. Splitting, Grouping, and Batch Output

Batch helpers matter because they operate directly on parsed interchanges. This is still parser-centric work, unlike external scheduling, mail alerts, or UI workflow design.

using HIPAAsuite.AuroraParser.Helpers;

FileSplitter.ProcessAndValidateInterchangesToDirectories(
    handler.Interchanges,
    Path.Combine(outputRoot, "Good"),
    Path.Combine(outputRoot, "Bad"),
    Path.GetFileName(inputPath),
    updateICN: true,
    updateFGCN: true,
    updateTSCN: true
);

8. What to Read First

The most useful reading order stays tight:

1. HIPAAsuite.AuroraParser first.
2. Read handler, parser, validator, and split-helper paths before anything else.
3. Only move outward when the parser behavior is already clear.

Do not let outer integration layers define your understanding of the parser.