API Reference Documentation

This reference covers the backend architecture, AWS services, and key APIs that power the Aitium platform. It is intended for developers and technical stakeholders.

Architecture Overview

Aitium’s backend is built entirely on AWS using the following managed services:

AWS Lambda — Serverless compute for all backend logic (Python and Node.js runtimes).
Amazon DynamoDB — NoSQL database for user, job, and subscription data.
Amazon S3 — Object storage for reports, inventory snapshots, and forecast results.
AWS Step Functions — Workflow orchestration for multi-step processes.
Amazon SQS — Message queuing for SP-API notifications and AWS Marketplace events.
Amazon Cognito — User authentication and authorization.
Amazon Forecast — Managed ML service for time-series predictions.
Amazon EventBridge — Scheduled rules for daily data refresh triggers.
AWS AppSync — Managed GraphQL API for frontend-backend communication.

Lambda Functions

Function	Runtime	Purpose
`OnBoardingSubscriptions`	Python	User authorization, subscription validation, SP-API notification setup, and initial data backfill trigger.
`aitiumV2DataKioskIngest`	Python	Submits Amazon DataKiosk GraphQL queries for historical and daily sales/traffic data.
`aitiumV2DailyTrigger`	Python	Amazon EventBridge–triggered function that creates rolling 30-day refresh jobs and daily buyer data jobs.
`aitiumV2SpApiSqsPoller`	Python	Processes Amazon SQS notifications from SP-API, downloads completed reports, and stores data in Amazon S3.
`aitiumV2GetAmazonBuyerDetails`	Python	Processes buyer intelligence data from the SP-API Orders API.
`aitiumV2InventoryIngestJob`	Python	Orchestrates inventory data ingestion across all user marketplaces.
`aitiumV2InventoryIngest`	Python	Processes FBA and MFN inventory data via direct invocation.
`aitiumV2ForecastJobHandler`	Python	Orchestrates Amazon Forecast job creation and lifecycle management.
`aitiumV2AFLauncher`	Python	Launches Amazon Forecast jobs for specific datasets.
`aitiumV2RFCodegen`	Python	Handles SP-API refresh token exchange and notification destination setup.
`SubscriptionData`	Python	Processes Stripe webhooks and AWS Marketplace entitlement notifications.
`createStripeCheckoutSession`	Node.js	Creates Stripe payment sessions for new subscriptions.
`aitiumV2InviteUser`	Node.js	Handles organization member invitations with subscription tier inheritance.
`aitiumV2AddOrgGroup`	Node.js	Manages Amazon Cognito group assignments and organization subject attributes.

DynamoDB Tables

Table	Primary Key	Purpose
`User`	`id` (email)	User profiles, subscription status, refresh tokens, and organization membership.
`IngestJob`	`id`	Tracks SP-API report ingestion jobs with status (PENDING → COMPLETE).
`Job`	`id`	Links IngestJobs to users. Amazon DynamoDB Streams trigger downstream processing.
`BuyerDataIngestJob`	`id`	Tracks buyer intelligence data ingestion jobs.
`DataKioskJob`	`id`	Tracks Amazon DataKiosk GraphQL query jobs for sales/traffic data.
`ForecastJob`	`id`	Tracks Amazon Forecast job lifecycle and results.

S3 Data Structure

s3://<bucket>/private/{identityID}/
├── SalesAndTrafficReport/       # DataKiosk sales & traffic data
├── OrdersByDate/                # Order data
├── {marketplace}_Inventory/
│   ├── AFN/                     # FBA inventory snapshots
│   └── MFN/                     # Merchant Fulfilled inventory
├── buyer-data/                  # Buyer intelligence
├── forecasts/
│   ├── sales/                   # Sales forecast results
│   └── inventory/               # Inventory forecast results
└── unique_buyers/               # Aggregated buyer CSVs

Step Functions State Machines

State Machine	Purpose
`aitiumV2call-auto-forecast`	Automated forecast scheduling and triggering.
`aitiumv2autoforecast`	Forecast execution pipeline: dataset import → predictor training → forecast generation → result export.
`aitiumV2B2BIngest`	B2B data processing pipeline for Amazon Business analytics.
`aitiumV2InventoryIngest`	Inventory data processing across FBA and MFN channels.

GraphQL API (AWS AppSync)

Aitium uses an AWS AppSync GraphQL API (managed by AWS Amplify) for frontend-backend communication.

Key Queries:

getUser — Retrieve user profile and subscription status.
getIngestJob / getForecastJob — Retrieve job details by ID.
forecastsByDate — List forecasts within a date range.
listForecastJobs / listJobs — List all jobs for the current user.
usersBySubject — Look up users by Amazon Cognito subject (used for organization member queries).
getSubscriptionStatus — Check active subscription status.
getPresignedOrgFileUrl — Generate presigned Amazon S3 URLs for organization file access.

Key Mutations:

createForecastJob — Launch a new Amazon Forecast job.
createIngestJob / createJob — Create data ingestion jobs.
createBuyerDataIngestJob — Create buyer intelligence ingestion jobs.
updateUser / updateForecastJob — Update records.

Subscriptions: Real-time updates for job status changes via WebSocket.

Authentication

Authentication is handled by Amazon Cognito. The frontend uses the AWS Amplify withAuthenticator higher-order component. All API requests are authenticated via Amazon Cognito JWT tokens passed in the Authorization header.

Billing APIs

Stripe Integration:

Webhook events processed: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded, invoice.payment_failed.
Subscription tiers determined by plan amount: Business ($79/month or $749/year) and Enterprise ($109/month or $1,049/year).

AWS Marketplace Integration:

Entitlement notifications delivered via Amazon SNS → Amazon SQS → Lambda.
The AWS Marketplace Entitlement Service API validates active subscriptions.
Notification types handled: entitlement-updated, subscribe-success, unsubscribe-pending, unsubscribe-success.

SP-API Integration

Aitium integrates with the following Amazon Selling Partner API endpoints:

DataKiosk API — GraphQL-based data queries for sales and traffic reports.
Reports API — GET_MERCHANT_LISTINGS_ALL_DATA report type for MFN inventory.
Orders API — GET /orders/v0/orders, GET /orders/v0/orders/{orderId}/orderItems, GET /orders/v0/orders/{orderId}/buyerInfo for buyer intelligence.
Notifications API — /notifications/v1/destinations and /notifications/v1/subscriptions for event-driven report processing.

Environment Variables

Key environment variables used across Lambda functions:

Variable	Description
`API_AITIUMV2_USERTABLE_NAME`	Amazon DynamoDB User table name.
`API_AITIUMV2_INGESTJOBTABLE_NAME`	Amazon DynamoDB IngestJob table name.
`API_AITIUMV2_JOBTABLE_NAME`	Amazon DynamoDB Job table name.
`API_AITIUMV2_BUYERDATAINGESTJOBTABLE_NAME`	Amazon DynamoDB BuyerDataIngestJob table name.
`STORAGE_S3DATASTORAGE_BUCKETNAME`	Amazon S3 data storage bucket name.