MAGETECH ERP

1. Document Purpose

This document is the complete, professional, enterprise-grade technical specification for MageTech ERP, a customized ERP platform built on Odoo as its foundation.

It is written for:

• Software Architects, Backend Developers, Odoo Developers, Frontend Developers
• Database Administrators, DevOps Engineers, QA Engineers
• Project Managers, System Administrators, Technical Support Teams
• Future Maintenance Teams

It explains how MageTech ERP is designed, developed, configured, secured, deployed, tested, monitored, maintained, and extended, at sufficient technical depth that a new developer can continue development without depending entirely on the original team.

2. Product Overview

Product objective — centralize the organization's core business domains into one unified platform:

• CRM  ·  Sales  ·  Customers  ·  Projects  ·  Tasks  ·  Timesheets  ·  Finance & Invoicing  ·  Expenses
• Inventory  ·  Purchasing  ·  Employees  ·  Attendance  ·  Leave  ·  Recruitment
• Marketing  ·  Customer Support  ·  Documents  ·  Business Intelligence

3. Document Scope

This document covers, in order: System Architecture, Technology Stack, Odoo Architecture, Custom Module Architecture, Database Architecture, Application Architecture, Frontend Architecture, Backend Architecture, API Architecture, Authentication, Authorization, Security, Multi-company architecture, Data flow, Business workflows, AI architecture, Reporting architecture, File/document management, Notification architecture, Email architecture, Deployment, DevOps, CI/CD, Backup, Monitoring, Logging, Testing, Performance, Scalability, Disaster recovery, Maintenance, Troubleshooting, Development standards, Coding standards, and the Future roadmap.

An executive summary of the current state follows. The full layered architecture is detailed in Part II.

4. High-Level System Architecture Implemented Recommended

MageTech ERP is designed as a layered architecture.

Layer 1 — Presentation Layer

Web UI, responsive UI, dashboard, forms, kanban, list views, calendar, Gantt, reports, notifications, mobile-responsive interfaces.

Technology: Odoo Web Client, OWL framework, JavaScript, XML templates, SCSS/CSS.

Layer 2 — Application Layer

Business logic: Odoo ORM, Python, business models, services, scheduled jobs, workflow logic, validation, automation.

Layer 3 — Integration Layer

Communication with external services: REST APIs, webhooks, payment gateways, email/SMS/WhatsApp providers, AI APIs, cloud storage, accounting integrations, third-party services. Planned

Layer 4 — Data Layer

Primary database PostgreSQL — business data, user data, transactions, configuration, audit information, attachment metadata.

Layer 5 — Infrastructure Layer

Linux server, PostgreSQL, Odoo application server, Nginx, SSL/TLS, Redis (where required), object storage (where required), monitoring, backup infrastructure. Recommended (production)

5. Architecture Diagram

End-to-end data flow as deployed today (Implemented) with production targets marked (Recommended):

6. Technology Stack

Every technology is marked Required (actually used/required), Recommended, or Optional. Nothing is invented.

7. Odoo Architecture

Odoo is a modular low-code ERP framework. MageTech extends it without modifying core files. Key Odoo concepts in use:

• Modules — versioned addons with __manifest__.py, models, views, data, security, assets.
• Models / Fields — Python classes inheriting models.Model; fields declared in class attributes (e.g. magetech.audit.log).
• Views — form, list, kanban, calendar, dashboard (OWL client action) etc.
• Actions — window actions, client actions (used by the executive dashboard), server actions, automated actions.
• Menus — hierarchical ir.ui.menu structure (MageTech sidebar uses a custom OWL menu).
• Controllers — HTTP endpoints on the Odoo HTTP layer (REST/JSON-RPC/XML-RPC).
• ORM — env-based record sets, search/create/write/unlink, computed & related fields, constraints.
• Security — ir.model.access.csv (ACLs) and record rules for row-level access.
• Scheduled Actions — server-side cron jobs (e.g. reminders).
• QWeb Reports — HTML/PDF reports; Email Templates — QWeb bodies for transactional mail.
• Server Actions / Automated Actions — model actions & rules triggering on record event.
• Configuration Settings — res.config.settings pages for business configuration.

8. Custom Module Architecture

Recommended MageTech module set. Implemented modules ship today; the rest are Planned.

Each module documents (where applicable): purpose, dependencies, models, views, controllers, security, reports, scheduled actions, external integrations, main workflows. Dependency graph today:

9. Standard Module Structure

magetech_crm/
│
├── __init__.py
├── __manifest__.py
│
├── models/
│   ├── __init__.py
│   ├── lead.py
│   └── customer.py
│
├── views/
│   ├── lead_views.xml
│   └── customer_views.xml
│
├── security/
│   ├── ir.model.access.csv
│   └── security.xml
│
├── data/
│   └── data.xml
│
├── demo/
│   └── demo.xml
│
├── reports/
│   └── report.xml
│
├── controllers/
│   └── main.py
│
├── static/
│   └── src/
│       ├── js/
│       ├── css/
│       └── xml/
│
└── README.md

The Implemented modules follow this layout. Notable current structures: magetech_base uses security/, models/, views/, data/, demo/, static/description; magetech_theme uses static/src/scss|js|sidebar|webclient|quickcreate|fonts|img plus data/theme_templates.xml (QWeb overrides); magetech_dashboard uses static/src/dashboard (OWL component) and static/src/lib/chart.umd.min.js; magetech_demo uses hooks.py + post_init_hook.

10. Database Architecture

PostgreSQL is the primary database. Odoo manages schema generation from model definitions (data-driven ORM); the DBA role is mostly performance, backup, and indexes.

• Odoo standard tables — res_partner, res_users, res_groups, product_product, sale_order, account_move, project_project, hr_employee, ir_model, ir_attachment, mail_message, etc.
• Custom models — e.g. magetech_audit_log (audit log), res_config_settings extensions; all are normal Odoo tables with a surrogate id and ORM-managed relation columns.
• Relationships — one2many / many2one / many2many fields become foreign-key and M2M junction tables.
• Indexing — Odoo auto-creates indexes for typical lookups; add explicit index=True or CONSTRAINT where query paths require it. Recommended: review slow queries on search paths.
• Constraints — model _sql_constraints enforce uniqueness/integrity.
• Transactions — ORM wraps requests in transactions; commit on success, rollback on exception.
• Referential integrity — enforced by PostgreSQL (FK constraints created from relational fields).

11. Entity Relationship Model

Core business entities and their cardinality. This is the target model — items marked Planned are not yet implemented.

Relationship notes: Customers hold 1:N leads/orders/invoices/payments. Projects hold 1:N tasks. Tasks hold N:N assignees and 1:N timesheets. One presence of each planned (non-implemented) entity is explicitly flagged; the dashboard today reads real Odoo records (partners, leads, projects, employees, sale orders) — no hard-coded production values.

12. CRM Architecture

Lead lifecycle (Odoo CRM):

13. Sales Architecture

14. Project Management Architecture

Projects → Milestones Planned → Tasks → Development → Testing → Review → Completed.

15. Finance Architecture

• Customers, Vendors, Invoices, Bills, Payments, Expenses, Taxes, Accounts, Financial reports.
• Integration with Odoo Accounting: account.move drives invoices/bills; payments reconcile via account.payment.

16. HR Architecture

Employees, Departments, Attendance, Leave, Recruitment, Payroll (if enabled).

Hierarchy: Company → Department → Manager → Employee.

17. Inventory Architecture

Products, product categories, warehouses, locations, stock moves, purchase, sales, inventory valuation. Stock movement lifecycle: Creation → Reservation → Transfer → Done. Planned: full magetech_inventory warehouse/location workflows; inventory valuation configuration Recommended.

18. Support Architecture

Tickets, customers, agents, priorities, SLA, status, resolution, escalation.

Planned: magetech_support module (or Odoo Helpdesk) with SLA timers and escalation rules.

19. Document Management

• File uploads, attachments (ir.attachment), document categories, access permissions, versioning, lifecycle, retention, backup.

Planned: dedicated document categories + versioning + retention workflow; store attachments in object storage with signed URLs Recommended.

20. Notification Architecture

• In-app notifications (Odoo message bus) — Implemented via mail.
• Email notifications, activity reminders, scheduled notifications — Implemented core; channel/SMTP config is Recommended.
• Push notifications — Planned.

Examples to configure: invoice-due reminder, task assignment, leave approval, project deadline, lead follow-up.

21. Email Architecture

• SMTP configuration, email templates, transactional & notification emails, password reset, invoice/quotation emails.

Status: core email framework Implemented; outbound SMTP provider and template inventory Recommended.

22. API Architecture

For every API, document: Endpoint, Method, Authentication, Request, Response, Validation, Error response, Permissions, Rate limiting.

Native Odoo APIs available today: JSON-RPC (/jsonrpc), XML-RPC (/xmlrpc/2/db, /xmlrpc/2/common, /xmlrpc/2/object), and the web controllers (/web/login, /web/session etc.) — Implemented by the framework. MageTech custom APIs and third-party APIs are TBD/Planned.

23. Authentication

Flow: user opens /web/login → submits credentials → Odoo validates via password hash (PBKDF2-SHA512 by default) → session cookie issued → session tracked/expired server-side.

• Login, logout, password reset — Implemented (branded login page).
• Session handling (cookies, expiry) — Implemented by Odoo.
• Password policies & account lockout — Recommended (enable via system parameters / MFA server).
• Multi-factor authentication — Recommended (Odoo Enterprise feature; MFA planned for magetech_base).

24. Authorization (Role-Based Access Control)

Roles are implemented as custom res.groups in magetech_base Implemented:

Access is enforced through Groups, ACLs (ir.model.access.csv), and Record Rules (row-level). Company-level and department-level access rules for the new domains are Planned.

25. Multi-Company Architecture

The platform is designed so each company can have separate users, accounting, customers, products, warehouses, documents, and configuration Recommended.

Odoo's native multi-company mechanism is used: company_id on records, allowed_company_ids on the session, company-scoped record rules, and ir.config_parameter by company where supported. No code changes are required for the base pattern; domain modules will respect company_id.

26. Multi-Tenancy (SaaS)

27. AI Architecture Planned

MageTech AI may provide: AI Lead Scoring, AI Sales Assistant, AI Customer Summary, AI Project Risk Detection, AI Business Summary.

Design considerations: AI provider, API integration, authentication, prompt management, data privacy, token usage, error handling, rate limits, logging, cost control.

28. AI Data Flow

AI-generated results must be clearly identified where appropriate. Business-critical decisions must not rely solely on AI output.

29. Dashboard Architecture Implemented

The executive dashboard is an OWL client action (magetech_dashboard.MagetechDashboard) loaded through ir.actions.client (tag: magetech_dashboard.main), reading real Odoo records via an RPC/ORM service.

• KPIs: Revenue, Outstanding, Active Projects, New Leads (counts/pipelines computed from records).
• Charts: Revenue Trend (Chart.js line) and Sales Pipeline (funnel).
• Below: Top Customers table and Recent Activity timeline.
• States: loading skeleton, error (with Retry), empty, ready.

30. Reporting Architecture

• Sales, Revenue, Finance, CRM, Project, HR, Inventory, Marketing reports.
• Each report should support date filters, user filters, company filters, export, PDF, and Excel/CSV where supported.

Recommended: build with QWeb (PDF) + pivot/list exports (XLSX/CSV) over the reporting module. Planned: magetech_reports domain packs.

31. Frontend Architecture Implemented

• Odoo frontend architecture and OWL for custom components (sidebar, dashboard, quick-create).
• Components, services, state management, templates, assets, JS modules, CSS/SCSS, responsive design.
• Asset bundles: web.assets_backend (theme+sidebar+dashboard) and web.assets_frontend (login).

Reusable component pattern Recommended: KPI cards (built), charts (built), tables (built), filters/modals/notifications/command palette/timeline/status badges (reusable on roadmap).

32. UI/UX Design System

The MageTech design system is implemented in magetech_theme SCSS using CSS custom properties Implemented:

Covers: colors, typography (Inter, bundled locally), spacing, buttons, cards, forms, tables, icons (FontAwesome), modals, alerts, status badges, dark mode (persisted preference), responsive rules. Modern, corporate, premium, consistent.

33. Animation Guidelines Recommended Implemented

Subtle professional animations: page transitions, card hover (implemented in KPI/kanban), KPI counters, chart animations (Chart.js, implemented), modal transitions, notification animations, loading skeletons (implemented), progress animations. Animations must not interfere with accessibility or performance; respect prefers-reduced-motion.

34. Security Architecture

Application Layer

• Authentication (session/password hashing), authorization (ACLs + record rules), input validation (ORM + _check), CSRF protection (Odoo CSRF token on forms).

Database Layer

• Credentials with least privilege, encryption at rest where applicable, secured backups.

Network Layer

• HTTPS (Nginx + TLS), firewall, reverse proxy, restricted ports (8069 internal only).

Infrastructure Layer

• SSH hardening (keys only), OS patching, secrets management, monitoring.

Recommended: all production layers; local dev is per §41.

35. Data Protection

• Data classification, sensitive-information handling, access control, encryption, backup, retention, deletion, audit logs.
• Follow applicable Indian data-protection requirements and contractual obligations where relevant.

36. Audit Logging Implemented

An audit log model magetech.audit.log exists with access rules Implemented:

Target events (capture as they occur): login, logout, record creation/modification/deletion, permission changes, configuration changes, financial changes. Each audit entry should record user, action, record, timestamp, relevant metadata.

37. File Storage

Attachment storage options: local filesystem Implemented (default filestore), object storage, cloud storage Recommended. Production target: Odoo → Object Storage using secure signed (pre-signed) URLs where appropriate.

38. Backup Architecture

Back up: PostgreSQL database, filestore, configuration (odoo.conf, env), custom modules (Git), deployment configuration.

39. Disaster Recovery

Targets (to confirm with business): RPO ≤ 24h daily backups (stretch: minutes with WAL), RTO ≤ 4h (TBD). Restoration order: restore PostgreSQL → filestore → config → application (modules from Git) → verify login/financial books → DNS/SSL as applicable. A full DR procedure is Recommended.

40. Deployment Architecture

Staging and production are documented separately in §41. Development currently runs on Windows with a local Python venv; production target is Ubuntu Linux + Nginx.

41. Environments

42. CI/CD Planned

43. Version Control Implemented

Git is in use on this repository. Recommended branching strategy:

main
develop
feature/*
bugfix/*
release/*
hotfix/*

• Commit conventions: concise conventional messages; one logical change per commit.
• Pull requests with code review before merge to main.
• Version tags (v1.0.0...) aligned to module version fields.

44. Testing Strategy

• Unit Testing — models and functions (Odoo test framework).
• Integration Testing — module interactions.
• API Testing — endpoint contracts (once APIs exist).
• UI Testing — frontend/flows (Playwright available in the toolchain).
• Security Testing — permissions and vulnerability review.
• Performance Testing — expected workloads.
• User Acceptance Testing — business validation.

Status: baseline QA via manual + scripted browser verification Implemented; full automated suite Planned.

45. Test Case Documentation

Each case: Test ID, Description, Preconditions, Steps, Expected result, Actual result, Status.

46. Performance Architecture

• Database indexing, query optimization, pagination, caching (Odoo asset/field caching), asset optimization (bundles, SCSS compile), background jobs (cron workers), worker configuration.
• Avoid loading large datasets unnecessarily (dashboard uses aggregated reads).

Status: progressive improvements Recommended; baseline acceptable at current data volumes.

47. Scalability

Horizontal scaling (multi-worker/multi-instance behind LB), vertical scaling (CPU/RAM), database scaling (optimized queries → read replicas/PCI), worker scaling, file-storage scaling (object storage). Recommended for production.

48. Monitoring

Monitor server CPU, memory, disk, database, Odoo workers, request latency, error rates, background jobs, backup status. Define alerts for critical conditions (e.g., 5xx rate, disk > 85%, worker saturation, backup failure). Tooling: Prometheus + Grafana, app error tracking Sentry Recommended.

49. Logging

Centralize Odoo logs, Nginx logs, PostgreSQL logs, application errors, security events.

50. Environment Variables

Provide .env.example (not .env) in the repository; never commit secrets.

# .env.example — copy to .env and fill with real values. NEVER commit .env
ODOO_DB_HOST=127.0.0.1
ODOO_DB_PORT=5432
ODOO_DB_USER=change_me
ODOO_DB_PASSWORD=change_me
ODOO_ADMIN_PASSWORD=change_me
SMTP_HOST=change_me
SMTP_PORT=587
SMTP_USERNAME=change_me
SMTP_PASSWORD=change_me
AI_API_KEY=change_me            # only if AI enabled
STORAGE_ACCESS_KEY=change_me    # only if object storage used
STORAGE_SECRET_KEY=change_me

51. Configuration Management

Separate application configuration, environment configuration, secrets, and business configuration. Do not hard-code production settings. Locally, odoo.conf holds dev connection values; production uses env-injected secrets.

52. Sample Data Implemented

The magetech_demo module seeds DEMO data idempotently via a post_init_hook (hooks.py). Every record set is clearly informational/demo — no production data.

53. Data Migration

Possible sources: Excel, CSV, existing CRM, existing accounting software, existing ERP. TBD until a source is confirmed. Never directly import unvalidated production data.

54. Third-Party Integrations

Integration architecture for: payment gateway, email, SMS, WhatsApp, Google services, Microsoft services, AI providers, cloud storage.

For each: purpose, API, authentication, data exchanged, failure handling, rate limits, security. All currently Planned/TBD — none are wired into production yet.

55. Error Handling

User-facing errors must be clear. Example: "Unable to create invoice" — "Please verify the customer and invoice details and try again." Technical errors are logged internally.

Never expose stack traces, database errors, API keys, or internal paths to normal users.

56. API Error Format

Consistent API response contract (target):

// Failure
{
  "success": false,
  "error": {
    "code": "CUSTOMER_NOT_FOUND",
    "message": "Customer could not be found."
  }
}

// Success
{
  "success": true,
  "data": {}
}

57. Development Coding Standards

58. Odoo Development Rules

1. Avoid modifying Odoo core files.
2. Use inheritance (_inherit / QWeb xpath with hasclass()).
3. Use custom modules for all changes.
4. Use ORM methods rather than raw SQL (except where strictly necessary).
5. Define proper access rights.
6. Define record rules for row-level security.
7. Add module dependencies correctly in __manifest__.py.
8. Provide upgrade scripts when necessary.
9. Keep business logic server-side.
10. Avoid hard-coded configuration.

59. Administration Guide

• Creating users, assigning roles, creating companies, configuring email, accounting, warehouses, products, managing permissions, managing backups, monitoring system health.
• Role assignment uses the groups from §24; admin console at /web#action=base_setup.act_base_settings.

60. User Guide Structure

61. Troubleshooting Guide

62. Security Checklist (before production)

• HTTPS enabled
• Strong database password
• Strong Odoo admin password
• Default accounts secured
• Debug mode disabled
• Database ports restricted
• Firewall configured
• Backups enabled
• Backup restoration tested
• Secrets removed from source
• Access permissions reviewed
• Audit logging enabled
• Dependencies updated

63. Production Deployment Checklist

Infrastructure

• Server configured
• PostgreSQL configured
• Odoo configured
• Nginx configured
• SSL configured

Application

• Custom modules installed
• Configuration verified
• Demo data removed if required
• Production data imported

Security

• Users configured
• Permissions verified
• Secrets secured
• Firewall enabled

Backup

• Database backup configured
• Filestore backup configured
• Restore tested

Monitoring

• Logs configured
• Alerts configured
• Server monitoring enabled

64. Technical Risks

Probability and Impact are estimates only and must be validated with evidence before use in planning.

65. Future Roadmap

66. Technical Glossary

67. Documentation Rules

1. Do not invent implementation details.
2. Clearly distinguish Implemented, Planned, and Recommended functionality.
3. Do not claim an API exists unless it has actually been implemented.
4. Do not claim an integration exists unless configured.
5. Do not expose credentials or secrets.
6. Use diagrams wherever they improve understanding.
7. Include tables for configuration and module information.
8. Include code snippets only where useful.
9. Use consistent terminology.
10. Maintain version history.

68. Document Version History

Document Control: Owner — MageTech Solutions Architecture. Review cycle — quarterly or on significant architecture change.

69. Final Document Structure

The document contains: Cover Page, Document Control, Revision History, Table of Contents (auto-generated), Executive Summary, Product Overview, System Scope, Functional Architecture, Technical Architecture, Technology Stack, Odoo Architecture, Custom Module Architecture, Database Architecture, ER Diagram, API Architecture, Security Architecture, Authentication & Authorization, Business Workflows, AI Architecture, Reporting Architecture, Integration Architecture, Deployment Architecture, Infrastructure, CI/CD, Testing Strategy, Performance, Scalability, Monitoring, Backup & Disaster Recovery, Administration, Troubleshooting, Security Checklist, Production Checklist, Technical Risks, Future Roadmap, Glossary, Appendices.

70. Final Quality Requirement

This document is intended to look like a professional technical document prepared by an enterprise software architecture team: detailed, structured, professional, developer-friendly, implementation-oriented, easy to maintain, suitable for client/internal documentation, future developers, and deployment/operations teams. Missing or un-finalized information is explicitly marked TBD / Planned / Recommended — the current implementation, planned features, and future recommendations are always distinguishable.

71. Pricing & Commercial Model

This section defines the commercial framework for delivering and supporting MageTech ERP. 2026 India market reference: ordinary Odoo implementations range from a few lakhs for smaller deployments to ₹15 lakh+ for more customized implementations; complex multi-company / custom ERP projects go substantially higher. Odoo also separates its subscription/licensing from implementation services — MageTech ERP follows the same structure: implementation + deployment + annual maintenance as distinct components.

Recommended MageTech ERP Packages

What ₹9,90,000 Can Include

*AI features depend on the actual implementation; AI API usage costs are billed separately (usage-based) rather than absorbed into the AMC.

Scope Boundaries — Included vs. Additional

Annual AMC Options

Major new features are managed as separate change requests — not unlimited development inside the AMC.

Better Commercial Model — Three Stages

Suggested Payment Schedule (₹9,90,000 Implementation)

Milestone-based billing is much safer than collecting the entire amount only at the end of the project.

Toward a Repeatable Product Pricing Model

Because MageTech ERP is being built as a commercial product for multiple customers, MageTech Solutions maintains a standardized pricing model instead of negotiating every customer from zero.