Event-Driven Processing System

🚀 Introduction

This project implements a scalable and reliable event-driven processing system using FastAPI, PostgreSQL, and asynchronous task execution. The system ensures that incoming requests are handled efficiently, triggering background processes without blocking the main application, making it ideal for processing external API calls, task scheduling, or data workflows.

---

🚀 Features

• FastAPI Backend: Exposes a REST API endpoint that handles incoming requests and stores data in a transactional database.
• PostgreSQL Database: Utilizes PostgreSQL to persist critical data, ensuring ACID compliance for reliability.
• Event-Driven Architecture: The system relies on an event-driven model where background processes, like interacting with external services, are triggered asynchronously without blocking the main application flow.
• External Service Integration: In response to specific requests, the system guarantees that relevant actions are performed in external services, such as invoking third-party APIs.
• Error Handling: Comprehensive error handling ensures that any failure in the process triggers a standardized error response with a helpful message, ensuring transparency.
• Scalable and Reliable: The design focuses on scalability and fault tolerance, ensuring that the system can handle increasing traffic and that external service failures do not affect the core API.

---

🚀 Used Technologies

• FastAPI: High-performance framework for building APIs with Python 3.7+.
• PostgreSQL: Robust, open-source relational database for data management.
• Docker Compose: Simplified multi-container management for easy setup and isolated development environments.
• DevContainers: Seamless integration with Visual Studio Code, offering a consistent and reproducible development environment.
• Standard Docker Setup: Supports non-VS Code users with a straightforward Docker Compose configuration.

---

💡 Getting Started

Prerequisites

Before you begin, make sure you have the following installed:

• Docker & Docker Compose (for containerization)
• Visual Studio Code (optional, for DevContainer integration)
• Git (to clone the repository)

---

🖥️ For Visual Studio Code Users

1. Clone the repository:

   git clone https://github.com/junior92jr/fastapi-docker-postgres-devcontainer-seed.git
   cd fastapi-docker-postgres-devcontainer-seed

2. Open the project in VS Code: Open the project folder in Visual Studio Code.

3. Automatically configure your DevContainer: Once inside VS Code, it will automatically prompt you to reopen the folder inside the DevContainer (defined in .devcontainer/devcontainer.json).

4. Run the application: Use Docker Compose to start the FastAPI app along with the PostgreSQL database by running:

   docker-compose up --build

   The application will be running and available at http://localhost:<port> (where <port> is defined in your .env file).

---

🛠️ For Non-VS Code Users

1. Clone the repository:

   git clone https://github.com/junior92jr/fastapi-docker-postgres-devcontainer-seed.git
   cd fastapi-docker-postgres-devcontainer-seed

2. Set up the .env file: Copy the example .env_sample file to create your own .env file.

   cp .env_sample .env

3. Edit the .env file (Optional): Open and edit the .env file to update any environment variables (e.g., database configurations, API keys).

4. Build and start the Docker containers:

   For older Docker versions (using docker-compose):

   docker-compose up --build

   For newer Docker versions (using docker compose):

   docker compose up --build

   This will build the necessary images and start the containers, creating the FastAPI app connected to a PostgreSQL database.

5. Access the application: Once the containers are running, open a browser and go to http://localhost:<port> (replace <port> with the port configured in .env or docker-compose.yml).

6. Run in detached mode (Optional): To run the containers in the background, use the -d flag:

   For older Docker versions:

   docker-compose up --build -d

   For newer Docker versions:

   docker compose up --build -d

7. Stop the containers: To stop the containers when you're done, use:

   For older Docker versions:

   docker-compose down

   For newer Docker versions:

   docker compose down

---

🧪 Running Tests

1. Access the running container:

   Use the following command to access the app container:

   docker exec -it <container_name> /bin/bash

   Replace <container_name> with the name of your app container, which you can find by running:

   docker ps

2. Navigate to the project directory (if not already there):

   cd /path/to/your/project

3. Run the tests:

   Execute the tests using pytest:

   pytest

   You can also specify specific test files or directories:

   pytest path/to/test_file.py

4. Exit the container:

   Once done, exit the container:

   exit

---

📝 Additional Notes

• If you're using Docker Desktop, you can easily manage containers through the GUI interface.
• This template uses Docker Compose to manage multi-container environments for both development and production.
• The .env file includes various environment variables for configuration—make sure to customize it according to your needs.
• To customize the FastAPI application, simply modify the code in the app directory.

---

🎯 Contributing

Feel free to fork this project and submit pull requests! Contributions are always welcome.