Skip to content

Introduction

🧭 What is Atlas?

Atlas is a Python-based framework designed for building cost-effective serverless APIs on AWS, with a strong focus on structure, consistency, and maintainability.

It provides a well-defined architecture composed of cohesive packages and internal resources that abstract away common concerns such as database persistence, request validation, error handling, business logic layering and cloud infrastructure — all customizable and ready to use.

From low-level infrastructure components to high-level application abstractions — Atlas is designed to integrate seamlessly, enabling developers to focus on domain logic rather than repetitive boilerplate or concerns about infrastructure development and organization.

By leveraging AWS services such as Lambda, API Gateway, and CloudFront, Atlas minimizes operational overhead and infrastructure costs, offering a scalable and cost-efficient foundation for your modern API development needs. It follows principles of clean architecture, layered design, and explicit validation, making it a robust and sustainable choice for production-grade applications.

💎 Features

In addition to the beneficial serverless aspects of Atlas, here are some of its key features:

  • 🧱 Easy-to-use layered architecture design;
  • 🧩 Several generic and importable modules to simplify the development process;
  • 🚀 Ready-to-use parameterized infrastructure and application deployment interface built with AWS CDK;
  • 🔧 Customizable API configuration parameters — memory size, timeout, authentication, throttle rate, request limiting, and more;
  • 🔐 Granular permission system integrated with API Gateway and DynamoDB, enabling fine-grained custom access control for each endpoint;
  • 🗄️ Automatic database migration system that stores the files securely in S3, keeping your repo clean;
  • 🧪 Local debugging environment that accurately simulates the AWS Lambda runtime for rapid testing and development;
  • 🔗 Extensible modular design that allows partial adoption or full integration into existing codebases;
  • 🛡️ Production-ready by default — designed to scale securely with AWS best practices;

🏗️ Architecture

Atlas is structured so that each API built upon it acts as a "blueprint" — a precise recipe for provisioning AWS resources in a consistent, controlled, and predictable way.

An Atlas application is essentially a collection of AWS Lambda functions programmatically parameterized, deployed and orchestrated within the AWS cloud. This collection, integrated with API Gateway and exposed exclusively through CloudFront as a secure reverse-proxy delivery layer, forms the foundation of the API itself.

The following diagram provides a simplified overview of how the Atlas-based API will be structured and managed in AWS once deployed.

Atlas Architecture Diagram

Once succesfully deployed into the AWS environment as a CloudFormation Stack, each controller layer handler (defined in directories inside src.functions) will be created as a Lambda function and, then, be integrated with the REST API interface provided by API Gateway.

The integrated Authorizer Lambda function, if enabled, will evaluate each request and allow or deny access to your Lambda functions — your API's endpoints. Requests denied by the Authorizer won't trigger your endpoints execution, therefore reducing potential costs (but the Authorizer's Lambda function execution will be accounted).

CloudFront acts as a reverse-proxy — receiving requests from the client, injecting a x-api-key header into it (containing an internal API Gateway key, responsible for enabling a general Usage Plan for the entire application and customizable infrastructure settings such as throttle rate and request quota) and proceeding to redirect the request to the API Gateway interface.

When following the project structure guidelines, each Lambda function in Atlas follows a clean layered architecture built around the three classic layers: controller (Lambda handlers), service, and repository.

Except for the controller layer and its private components — such as request and response DTOs — all other code elements are placed within the shared internal or libraries Lambda layers, ensuring modularity, reusability, and minimal code duplication across functions.