The Claims Service is a backend API built with Node.js and TypeScript, designed for ingesting and querying healthcare claims CSV files.
It follows the principles of Hexagonal Architecture (Ports & Adapters), focusing on clarity, testability, extensibility, and simplicity.

This project simulates a real-world internal service used by customer support agents to:

• Upload daily claim exports from a legacy system
• Validate and normalize incoming data
• Store them temporarily in memory
• Allow filtering and querying for specific claims

• ✅ Hexagonal Architecture (Domain → Application → Adapters)
• ✅ Node.js + TypeScript with strict type checking
• ✅ Middy middleware framework (AWS Lambda simulation)
• ✅ Express.js for local development and debugging
• ✅ CSV ingestion with field validation and error reporting
• ✅ Filtering by memberId, startDate, and endDate
• ✅ Automatic sorting by serviceDate (descending)
• ✅ In-memory storage (mock repository)
• ✅ Ready for unit and integration testing using Jest
• ✅ Local execution via VSCode Debug or npm run dev
• ✅ Jest Parcial unit test coverage
• ✅ Husky and Linting

• Integrate an Inversion of Control (IoC) Framework
• Implement Real Database Integration (Dynamo, Mongo etc)
• Expand and Finalize Unit Test Coverage
• Create infrastructure and deploy the application
• Implement Role-Based Authorization (JTW)
• Integrate OpenTelemetry for Unified Observability / centralized error handling, logs and metrics
• Add Pagination Support for API Results
• This is a sample project / Not meant to production
• Use GitHub Security Tools for Code and Dependency Analysis

Note: This is a Sample Project (Not Intended for Production Use) The implementation is designed for educational and demonstration purposes only. Security, scalability, and resilience optimizations are intentionally simplified.

npm run dev

The local Express server runs on:

http://localhost:3000

curl -X POST   -H "Content-Type: text/plain"   --data-binary @sample.csv   http://localhost:3000/claims

Example Response

{
  "successCount": 4,
  "errorCount": 3,
  "errors": [
    { "row": 4, "message": "serviceDate cannot be in the future" },
    { "row": 5, "message": "Missing memberId" },
    { "row": 6, "message": "Invalid totalAmount (not a positive integer)" }
  ]
}

curl "http://localhost:3000/claims?memberId=MBR001&startDate=2025-05-01&endDate=2025-05-31"

Example Response

{
  "claims": [
    {
      "claimId": "CLM001",
      "memberId": "MBR001",
      "provider": "HealthCare Inc",
      "serviceDate": "2025-05-14",
      "totalAmount": 12500,
      "diagnosisCodes": ["R51", "K21.9"]
    }
  ],
  "totalAmountSum": 12500
}

This project follows the Hexagonal Architecture (Ports & Adapters) pattern:

            +----------------------------+
            |        Presentation        |
            |  (Express / Middy Handlers) |
            +-------------+--------------+
                          |
                          ▼
            +----------------------------+
            |        Application         |
            |  (Use Cases / Services)    |
            +-------------+--------------+
                          |
                          ▼
            +----------------------------+
            |           Domain           |
            | (Entities & Interfaces)    |
            +-------------+--------------+
                          |
                          ▼
            +----------------------------+
            |        Infrastructure      |
            | (Repository / Clock / IO)  |
            +----------------------------+

This separation ensures:

• Independence from frameworks
• Easy unit testing of business logic
• Clean dependency inversion

Tests implemented using Jest and structured per layer:

npm run test

Structure:

tests/
├── application/
│   └── ingest_claims_service.spec.ts
├── adapters/
│   ├── inbound/
│   └── out/
└── domain/

To debug locally in VSCode:

1. Open the Run and Debug tab
2. Select the configuration Debug Claims Service
3. Press F5

Breakpoints can be set anywhere in src/**/*.ts.

This is a personal project built for demonstration and technical assessment purposes.
However, contributions and suggestions are always welcome!

Feel free to:

• Submit pull requests
• Suggest improvements
• Report issues or open discussions

Thiago Ananias
Cloud Architect & Software Engineer
GitHub • LinkedIn

This project is licensed under the MIT License.
See LICENSE for details.