Cloud Native NAV API Documentation

This document describes the architecture, components, and deployment characteristics of the Cloud Native NAV API

Use Cases

The Invoice Processor Solution is intended to automate invoice ingestion and management using the Hungarian NAV API. Use cases include:

Automatic download and archival of invoices from NAV Online Szamla.
Invoice Database using DynamoDB.
Authenticated querying data from database.

Overview of Deployment

The CloudFormation template provisions the following resources:

DynamoDB table for structured invoice storage.
S3 buckets with encryption and versioning for storing invoice text files and frontend content.
Cognito User Pool and Client for authentication.
Lambda functions for processing and querying invoices.
API Gateway REST API to expose invoice data securely.
CloudFront distribution for frontend delivery and API acceleration.
EC2 deployer instance for building and deploying the frontend.
CloudWatch log groups for monitoring Lambda execution.
SSM parameter store to securely store NAV credentials.

Prerequisites

Before starting the deployment the account needs to have a VPC and a subnet set up with access to the public internet. Basic AWS Cloud Practitioner level knowledge is necessary for deployment.

Deployment Options

This solution is deployed as a regional serverless application. Multi-AZ or multi-region variants are not included but can be added with minor modifications.

Deployer Role

Do not use AWS account root user to deploy this application.

The deployer user needs permission to handle operations on resources mentioned in Overview of Deployment section.

Estimated Deployment Time

Typical deployment completes in approximately 10-15 minutes, depending on S3 object availability and EC2 instance initialization.

External Dependencies

The following external dependencies are dowloaded during deployment:

NVM v0.40.2
Node v22 (installed by NVM)
Lambda and WebUI source code is downloaded from seller's S3 bucket during deployment.

Supported AWS Regions

Compatible with all AWS regions that support:

Lambda (Python 3.13)
DynamoDB
S3
Cognito
API Gateway
CloudFront
EC2

Suggested default deployment regions: eu-central-1 however the used services are available in almost all regions.

Architecture Overview

The solution includes the following components:

API Gateway
Lambda (invoice processor and query functions)
DynamoDB
S3
Cognito
CloudFront
EC2 (frontend builder instance)

Component Diagram

Network Topology

Network Diagram

Billable Serice

The list of billable services can be found in Architecture Overview section.

Regional Isolation

All resources are provisioned in a single region. No cross-region references exist in the template. All resources are provisioned in a single AZ.

Resource Identifier Management

The template uses CloudFormation dynamic references such as !Ref, !Sub, and !GetAtt. No hardcoded ARNs or region/account-specific values are used.

IAM Usage

IAM roles are scoped according to the principle of least privilege. Examples:

Lambda roles are restricted to only required actions on DynamoDB, S3, and SSM.
EC2 role is scoped to limited S3 and EC2 actions.

Public Access and Security

Public access is blocked on all S3 buckets.
CloudFront with Origin Access Control ensures secure delivery.
HTTPS/TLS enforced for frontend and API access.

Sensitive Data Handling

Sensitive parameters such as NavLogin, NavPassword, and NavSignKey use NoEcho and are stored in SSM Parameter Store.

Encryption

S3 buckets use AES-256 encryption.
DynamoDB encryption is enabled by default.
All traffic between components is encrypted using HTTPS.

Software Components and Packaging

Lambda functions are packaged and versioned internally.
Frontend is deployed from an S3 bucket (cheppers-cegfigyelo-frontend) using an EC2 instance.

Password Policies

Cognito User Pool enforces strong password policies:

Minimum 8 characters
At least one uppercase, lowercase, number, and symbol

Update Process

Lambda code can be updated by uploading new ZIP files to S3.
CloudFormation stack updates can be used to roll out changes.
Frontend updates are handled via the EC2 deployer instance.

CloudFormation Practices

The template adheres to best practices:

Parameterization for environment-specific values
NoEcho for sensitive parameters
Resource tagging and outputs
Use of DeletionPolicy on persistent buckets

Usage instructions

Prerequisites Before deploying the application, ensure the following prerequisites are met:

You have an existing VPC and subnet configured with access to the public internet. No inbound access is required.
You have registered a Service User in the NAV Online Szamla (Online Invoice) application. This user's credentials will be required during setup.

Deployment Steps

Launch the CloudFormation Stack Deploy the provided AWS CloudFormation template to begin provisioning the resources.
Fill Out the Stack Parameters During the stack creation:
Complete all parameters based on the provided descriptions. For NAV-related parameters, use the credentials of your NAV Online Szamla service user. Set the TimePeriodToCheck parameter to a value between 1 and 30. This determines how many days back the application will check for invoices in NAV.
Access the Application UI Once the stack has been successfully deployed:
The application's UI will be accessible via the domain name output by the CloudFormation stack. On your first login, you will be prompted to set a new password for your account

Logging and Monitoring

CloudWatch Log Groups are created for Lambda functions with 30-day retention policies.Add commentMore actions IAM permissions are included for log management.

Dynamo DB Query Lambda Failure Handling

If the Lambda execution fails due to timeout or internal errors:

All failed events are logged in CloudWatch Log Group !Sub /aws/lambda/DynamoDBQueryFunction.
Developers can test failure scenarios using invalid workload. E.g.:
```
{
  "payload": "invalid"
}
```
To debug:
Go to CloudWatch → Log Groups → /aws/lambda/<LAMBDA_NAME>
Look for ERROR logs with RequestId
Use aws logs tail for real-time log monitoring.

Dynamo Invoice Processor Lambda Failure Handling

Use the same method as for Dynamo DB Query Lambda Failure Handling.

Monitoring Lambdas & DynamoDB

All Lambda invocations are logged in CloudWatch Log Group /aws/lambda/<LAMBDA_NAME>. CloudWatch Alarms:

In case of need the following CloudWatch alarms are suggested to be created:

LambdaErrorRateAlarm – triggers on error rate > 5%
DynamoDBThrottlingAlarm – monitors ProvisionedThroughputExceededException

Creating Lambda Error Rate Alarm

Step 1: Open CloudWatch Console

Go to AWS CloudWatch Console
Navigate to Alarms in the left menu
Click "Create alarm"

Step 2: Select Metric

Click “Select metric”
Go to: Lambda → By Function Name
Select the Errors metric for your Lambda function
Click "Select metric"

Step 3: Configure Metric & Conditions

Statistic: Sum
Period: 5 minutes (or as appropriate)
Threshold type: Static
Condition: is >= (e.g., 1 error)
(Optional) To monitor error rate > 5%, use metric math:
- Add both Errors and Invocations metrics
- Add math expression:
```
(errors / invocations) * 100
```
- Set threshold: >= 5

Step 4: Name & Create

Name the alarm: LambdaErrorRateAlarm
Click Next, then Create alarm

Creating DynamoDB Throttling Alarm

Step 1: Open CloudWatch Metrics

In CloudWatch Console, go to Metrics
Navigate to: DynamoDB → By Table Name

Step 2: Select Metric

Choose the metric: ThrottledRequests for your table
Click "Select metric"

Step 3: Configure Metric & Conditions

Period: 1 minute or 5 minutes
Threshold type: Static
Condition: >= 1

This implicitly monitors ProvisionedThroughputExceededException.

Step 4: Configure Actions

Choose or create an SNS topic
Notify on "In alarm" state

Step 5: Name & Create

Name the alarm: DynamoDBThrottlingAlarm
Click Next, then Create alarm

Logs

Access logs:

Navigate to CloudWatch Console
Go to Log Groups → /aws/lambda/DynamoDBQueryFunction
Filter for ERROR, Exception, or specific RequestId