Development Guide¶

Comprehensive guidelines and best practices for developing Odoo modules, Flask applications (PWA & Landing Page), and contributing to this project.

Development Environment¶

Prerequisites¶

Tool	Version	Purpose
Python	3.8+	Odoo and Flask runtime
Docker	20.10+	Container runtime
Docker Compose	2.0+	Container orchestration
Git	2.30+	Version control
VS Code	Latest	Recommended IDE
Node.js	18+	Landing Page (Tailwind CSS build)

Quick Setup¶

# Clone repository
git clone git@github.com:example/odoo15-production.git
cd odoo15-production

# Configure test environment
cp .env.example .env

# Start development environment
./production_deploy.sh start

# Verify services
./production_deploy.sh status

# Access services
open http://localhost:8016   # Odoo ERP
open http://localhost:8000   # Field PWA
open http://localhost        # Landing Page
open http://localhost:8002   # Documentation

Project Structure¶

odoo15-production/
├── docker-compose.yml          # Base Docker Compose
├── docker-compose.test.yml     # Test environment overlay
├── docker-compose.prod.yml     # Production environment overlay
├── production_deploy.sh        # Centralized deployment script
├── .env.example                # Environment template
│
├── configs/
│   └── odoo.conf              # Odoo configuration
│
├── extra-addons/
│   ├── odoo/                  # Custom Odoo modules
│   │   ├── jdx_core_data/
│   │   ├── justcall_sms/
│   │   ├── xero_integration/
│   │   └── ...
│   └── helpdesk/              # Helpdesk module stack
│
├── pwa/                       # Field PWA (Flask)
│   ├── app/
│   ├── Dockerfile
│   └── requirements.txt
│
├── landing-page/              # Landing Page (Flask + Tailwind)
│   ├── app/
│   ├── Dockerfile
│   └── tailwind.config.js
│
├── nginx/                     # Nginx configuration
│   ├── conf.d/
│   └── ssl/
│
├── scripts/                   # Utility scripts
│   ├── backup.sh
│   ├── ssl-init.sh
│   └── health-check.sh
│
└── docs/                      # Documentation (MkDocs)
    ├── mkdocs.yml
    └── content/

Development Workflow¶

Git Branching Strategy¶

gitGraph
    commit id: "main"
    branch develop
    commit id: "develop"
    branch feature/new-feature
    commit id: "feat: add feature"
    commit id: "test: add tests"
    checkout develop
    merge feature/new-feature
    checkout main
    merge develop tag: "v1.2.0"

Branch	Purpose	Merge Target
`main`	Production-ready code	-
`develop`	Integration branch	`main`
`feature/*`	New features	`develop`
`fix/*`	Bug fixes	`develop` or `main`
`hotfix/*`	Critical production fixes	`main`

Commit Message Convention¶

Follow Conventional Commits:

Type	Description	Example
`feat`	New feature	`feat: add SMS template support`
`fix`	Bug fix	`fix: resolve signature upload error`
`docs`	Documentation	`docs: update API authentication guide`
`refactor`	Code refactoring	`refactor: simplify order creation flow`
`test`	Tests	`test: add unit tests for SMS module`
`chore`	Maintenance	`chore: update dependencies`
`perf`	Performance	`perf: optimize database queries`

# Good commit messages
git commit -m "feat: add multi-line SMS support to justcall_sms"
git commit -m "fix: correct invoice sync timing in xero_integration"
git commit -m "docs: add Xero OAuth2 setup instructions"

# Bad commit messages
git commit -m "updated code"
git commit -m "fix bug"
git commit -m "changes"

Coding Standards¶

Python (Odoo Modules)¶

Follow PEP 8 style guide
Use Odoo ORM conventions and best practices
Write docstrings for public methods
Keep methods under 50 lines
Use meaningful variable and method names

# Good
def _compute_total_amount(self):
    """Compute total amount including taxes and discounts."""
    for record in self:
        record.total_amount = sum(line.subtotal for line in record.line_ids)

# Bad
def calc(self):
    for r in self:
        r.t = sum(l.s for l in r.l)

Python (Flask Apps)¶

Follow Flask application factory pattern
Use blueprints for route organization
Implement proper error handling
Add health check endpoints
Use environment variables for configuration

JavaScript¶

Use ES6+ syntax
Modular design with clear responsibilities
Add JSDoc comments for functions
Handle offline scenarios in PWA
Use meaningful variable names

Module Development¶

Creating a New Odoo Module¶

# Module structure
extra-addons/odoo/my_module/
├── __init__.py
├── __manifest__.py
├── models/
│   ├── __init__.py
│   └── my_model.py
├── views/
│   └── my_model_views.xml
├── security/
│   └── ir.model.access.csv
├── data/
│   └── data.xml
└── static/
    └── description/
        └── icon.png

Module Manifest Template¶

# __manifest__.py
{
    'name': 'My Module',
    'version': '15.0.1.0.0',
    'category': 'Custom',
    'summary': 'Brief module description',
    'description': """
        Detailed module description.
        - Feature 1
        - Feature 2
    """,
    'author': 'Your Company',
    'website': 'https://example.com',
    'license': 'LGPL-3',
    'depends': ['base', 'sale'],
    'data': [
        'security/ir.model.access.csv',
        'views/my_model_views.xml',
        'data/data.xml',
    ],
    'installable': True,
    'application': False,
    'auto_install': False,
}

Install/Update Module¶

# Install new module
docker compose exec odoo odoo -i my_module --stop-after-init -d $DB_NAME

# Update existing module
docker compose exec odoo odoo -u my_module --stop-after-init -d $DB_NAME

# Or use deployment script
./production_deploy.sh update-module my_module

Testing¶

Odoo Module Testing¶

# Run module tests
docker compose exec odoo odoo --test-enable -i module_name --stop-after-init -d $DB_NAME

# Run with test tags
docker compose exec odoo odoo --test-tags=/module_name --stop-after-init -d $DB_NAME

Flask Testing¶

# Run PWA tests
docker compose exec pwa python -m pytest

# Run with coverage
docker compose exec pwa python -m pytest --cov=app

Debugging¶

Odoo Debugging¶

# Access Odoo shell
./production_deploy.sh odoo-shell

# In shell
>>> env['res.partner'].search([('name', 'ilike', 'test')])
>>> env['sale.order'].browse(123).read()

Log Viewing¶

# View Odoo logs
./production_deploy.sh logs odoo

# View all logs
./production_deploy.sh logs

# Follow specific service logs
docker compose logs -f pwa

Database Access¶

# Access PostgreSQL
./production_deploy.sh db-shell

# In psql
\dt                    # List tables
\d res_partner         # Describe table
SELECT * FROM res_partner LIMIT 10;

Section Guides¶

Getting Started¶

Guide	Description
Onboarding Guide	New developer onboarding checklist
Environment Setup	Detailed local development setup

Development Guides¶

Guide	Description
Workflow Guide	Git workflow and code review process
Deployment Scripts	Using production_deploy.sh
Module Development	Creating Odoo modules
Database Migrations	Schema changes and migrations

Standards & Guidelines¶

Guide	Description
Coding Standards	Python, JavaScript, and Flask style guides
Naming Conventions	Module, file, and variable naming
Versioning Policy	Semantic versioning guidelines
Logging Standards	Logging best practices
Error Handling	Error handling patterns
Security Guidelines	Security best practices
Code Review	Code review checklist and process

Troubleshooting¶

Guide	Description
Troubleshooting Guide	Common issues and solutions
Debugging Guide	Debugging techniques and tools

Reference¶

Guide	Description
Architecture Overview	System architecture details
Architecture Decisions	ADRs documenting key decisions
Email Routing	Email configuration
Glossary	Project terminology

Contributing¶

Guide	Description
Testing	Testing strategies and tools
Contributing	How to contribute to the project

Quick Commands Reference¶

# Development
./production_deploy.sh start              # Start all services
./production_deploy.sh restart-service odoo  # Restart Odoo
./production_deploy.sh logs odoo          # View logs
./production_deploy.sh odoo-shell         # Odoo shell
./production_deploy.sh db-shell           # Database shell

# Module Management
./production_deploy.sh update-module MODULE_NAME  # Update module
docker compose exec odoo odoo -i MODULE -d DB --stop-after-init  # Install

# Rebuilding
./production_deploy.sh rebuild-pwa        # Rebuild PWA
./production_deploy.sh rebuild-landing    # Rebuild Landing Page
./production_deploy.sh rebuild-docs       # Rebuild Documentation
./production_deploy.sh rebuild-all        # Rebuild everything