Odoo Synchronization Backend

[karamih]

Odoo Synchronization Backend

Summary

This pull request provides the foundation of an Odoo synchronization service built with FastAPI, PostgreSQL, SQLAlchemy, Alembic, Docker, Nginx, and uv.

The project was designed using a layered architecture with a strong emphasis on maintainability, separation of concerns, and future extensibility. Rather than tightly coupling business logic with database or external integrations, responsibilities are separated into dedicated layers (API, Services, Repositories, Adapters, Models, Database, Schemas, etc.), making the codebase easier to extend and test.

---

Architecture Decisions

The project follows a layered architecture:

• API – HTTP endpoints only.
• Services – Business logic and synchronization workflows.
• Repositories – Database access abstraction.
• Models – SQLAlchemy ORM entities.
• Database – Engine, Session management and Alembic configuration.
• Adapters – External integrations (planned Odoo XML-RPC communication).
• Schemas – Pydantic request/response models.
• Utils/Core – Shared utilities and common functionality.

This separation allows each layer to have a single responsibility and keeps business logic independent from infrastructure details.

---

Infrastructure

The project is fully Dockerized.

Current services include:

• FastAPI Backend
• PostgreSQL (Backend)
• PostgreSQL (Odoo)
• Odoo
• Nginx Reverse Proxy

Health checks have been configured for all services, and all application configuration is managed through environment variables.

---

Seed Module

A dedicated seed module has been implemented separately from the backend.

The seed communicates with Odoo via XML-RPC and automatically populates the ERP with sample data, including:

• Contacts
• Products
• Sale Orders
• Sale Order Lines

Keeping the seed isolated from the backend allows data generation and testing without coupling it to the application itself.

A dedicated README is included inside the seed directory describing how to execute it.

---

Database

The following database components have been implemented:

• SQLAlchemy Engine
• Session Management
• Declarative Base
• Alembic Configuration
• Initial Migration
• ORM Models
• Repository Layer

Implemented entities:

• Contacts
• Products
• Sale Orders
• Sale Order Lines

Repository classes have also been created to isolate database access from business logic.

---

Running the Project

Start all services:

docker compose up --build

Before running the seed:

1. Wait until Odoo becomes available.
2. Log into Odoo.
3. Install the required applications (Contacts, Sales and Inventory).

Then execute the seed module following the instructions documented in:

seed/README.md

---

Development Commands

All backend development commands are executed inside the backend container using uv.

Examples:

Create migration:

docker compose exec backend uv run alembic revision --autogenerate -m "migration_name"

Apply migrations:

docker compose exec backend uv run alembic upgrade head

Run the test suite:

docker compose exec backend uv run pytest

---

Tests

Repository tests have been started as part of the project structure.

The testing infrastructure has been prepared using pytest and is intended to be expanded alongside the service layer implementation.

---

Known Limitations

Due to the available implementation time, the following planned components were not completed:

• Odoo synchronization services
• Adapter implementation for XML-RPC communication
• Retry mechanism
• Synchronization logging
• Synchronization history
• REST endpoints
• Complete automated test suite

However, the project architecture has been prepared specifically to accommodate these features without requiring significant structural changes.

---

Final Notes

The primary objective of this implementation was to establish a clean, scalable, and maintainable foundation for the synchronization service.

Although not every planned feature has been implemented, the project already includes the complete infrastructure setup, Dockerized environment, database layer, migration system, repository abstraction, automatic Odoo data seeding, and the architectural structure required for future development.