# infovpcs/odoo18_mcp_project architecture

> Architecture diagram of the GitHub repository infovpcs/odoo18_mcp_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/infovpcs/odoo18_mcp_project
- Repository: https://github.com/infovpcs/odoo18_mcp_project

## Overview

##### Project Type and Purpose
- This is a full-stack integration server combining an MCP (Master Control Program) SDK with an Odoo 18 ERP system.
- It offers both HTTP and STDIO interfaces (via mcp_server.py and standalone_mcp_server.py), a Streamlit UI, command-line scripts, and Claude Desktop integration.
- Core goals: dynamic model discovery, CRUD operations, export/import to CSV, advanced NLP search, AI-driven code and documentation generation.

##### Key Architectural Components
a. User Interfaces
- Command-line and script clients (scripts/dynamic_data_tool.py, various example *.py).
- Claude Desktop via MCP SDK (claude_config.json, update_claude_config.sh).
b. MCP Server
- mcp_server.py: FastAPI-based HTTP and STDIO tool dispatcher.
- Core request handlers (src/mcp/handlers.py, dynamic_handlers.py).
- Client code for STDIO and HTTP transports (src/mcp/client.py).
c. Odoo Integration
- XML-RPC Odoo client wrapper (src/odoo/client.py).
- Dynamic model discovery, CRUD generator, NLP analyzer (src/odoo/dynamic/…).
- Data schemas (src/odoo/schemas.py).
d. AI & RAG
- Odoo documentation RAG pipeline (src/odoo_docs_rag/): embedding storage (embeddings.db), FAISS index, Gemini summarizer, Brave online search.
- Simple and advanced code agents (src/simple_odoo_code_agent/ and src/odoo_code_agent/) implementing LangGraph workflows.
e. Export/Import Agents
- LangGraph agents for CSV export/import (src/agents/export_import/).
- Utility handlers for CSV, field mapping.
f. Data Stores & File System
- Odoo database (external).
- Local volumes: exports/, tmp/, generated_modules/, logs/.
- Document index files: odoo_docs_index/faiss_index.bin, embeddings.db.
g. Infrastructure
- Docker (Dockerfile, docker-compose*.yml).
- Makefile for build/test/dev/prod workflows.
- Environment variables (.env).
- CI/test suite (tests/).

##### Relationships and Data Flows
1. User (browser/CLI/Claude) → Streamlit or MCP SDK → MCP Server
2. MCP Server → Internal handlers →
a. Odoo XML-RPC client → Odoo ERP → returns data
b. AI clients (Gemini, Ollama, sentence-transformers + FAISS + Brave) → returns summaries/embeddings
3. MCP Server composes results and forwards back to user.
4. Export/Import flows: MCP or scripts → File system (exports/, tmp/) → agents → Odoo.
5. Code-generation: user query → code agent workflow → generated modules → stored in generated_modules/.
6. Documentation RAG: user query → docs_processor → embeddings → FAISS → summarizer → user.

##### Architectural Patterns & Technologies
- Modular monolith with layered packages: core, mcp, odoo, agents, UI.
- Agent-based workflows using LangGraph for export/import and code generation.
- Micro-service-style interfaces: FastAPI endpoints, standalone server.
- Asynchronous I/O (async/await for MCPConnector, FastAPI).
- Vector search (sentence-transformers + FAISS).
- Streamlit for rapid UI prototyping.
- Docker Compose for multi-container orchestration (mcp-server, standalone-server, test-runner).

##### Level-of-Detail Recommendations
- Essential architectural elements without overcrowding: group closely related modules.
- Dynamic discovery workflows (agents and RAG) as sub-flows.
- Docker Compose services and how volumes map to host directories.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer (Blue)
    subgraph "Presentation Layer" 
        direction TB
        StreamlitUI(["Streamlit UI"]):::ui
        CLI(["CLI Scripts"]):::ui
        Claude(["Claude Desktop"]):::ui
    end

    %% Application Layer (Green)
    subgraph "Application Layer (MCP Server)"
        direction TB
        MCP_HTTP(["mcp_server.py\n(FastAPI HTTP & STDIO)"]):::server
        MCP_STD(["standalone_mcp_server.py\n(STDIO only)"]):::server
        Handlers(["src/mcp/handlers.py"]):::server
        DynHandlers(["src/mcp/dynamic_handlers.py"]):::server
        MCPClient(["src/mcp/client.py"]):::server
    end

    %% Integration Layer (Orange)
    subgraph "Integration Layer"
        direction TB
        subgraph "Odoo Integration"
            OdooClient(["src/odoo/client.py"]):::ext
            ModelDisc(["src/odoo/dynamic/model_discovery.py"]):::ext
            CRUDGen(["src/odoo/dynamic/crud_generator.py"]):::ext
            FieldAnal(["src/odoo/dynamic/field_analyzer.py"]):::ext
            NLPAnal(["src/odoo/dynamic/nlp_analyzer.py"]):::ext
            Schemas(["src/odoo/schemas.py"]):::ext
        end
        subgraph "AI & RAG"
            DocsProc(["src/odoo_docs_rag/docs_processor.py"]):::ext
            DocsRet(["src/odoo_docs_rag/docs_retriever.py"]):::ext
            EmbEngine(["src/odoo_docs_rag/embedding_engine.py"]):::ext
            Summarizer(["src/odoo_docs_rag/gemini_summarizer.py"]):::ext
            OnlineSearch(["src/odoo_docs_rag/online_search.py"]):::ext
            DBStorage(["src/odoo_docs_rag/db_storage.py"]):::ext
            EmbDB(["odoo_docs_index/embeddings.db"]):::storage
            FaissIdx(["odoo_docs_index/faiss_index.bin"]):::storage
        end
        subgraph "Code Agents"
            SimpleAgent(["src/simple_odoo_code_agent/odoo_code_generator.py"]):::ext
            DeepWiki(["src/simple_odoo_code_agent/utils/deepwiki_client.py"]):::ext
            FileSaver(["src/simple_odoo_code_agent/utils/file_saver.py"]):::ext
        end
        subgraph "Export/Import Agents"
            EI_Main(["src/agents/export_import/main.py"]):::ext
            EI_Export(["src/agents/export_import/nodes/export_nodes.py"]):::ext
            EI_Import(["src/agents/export_import/nodes/import_nodes.py"]):::ext
            EI_State(["src/agents/export_import/state.py"]):::ext
            EI_CSV(["src/agents/export_import/utils/csv_handler.py"]):::ext
            EI_Map(["src/agents/export_import/utils/field_mapper.py"]):::ext
        end
    end

    %% Data Layer (Gray)
    subgraph "Data Layer"
        direction TB
        OdooDB(["Odoo 18 DB\n(port 8069)"]):::db
        ExportFS(["exports/ , tmp/, generated_modules/, logs/"]):::storage
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        DockerfileNode(["Dockerfile\nentrypoint.sh"]):::infra
        Compose(["docker-compose*.yml"]):::infra
        Env([".env.example"]):::infra
        MakefileNode(["Makefile"]):::infra
    end

    %% Flows
    StreamlitUI -->|HTTP| MCP_HTTP
    CLI -->|STDIO/HTTP| MCP_HTTP
    CLI -->|STDIO| MCP_STD
    Claude -->|MCP SDK| MCPClient
    MCPClient --> MCP_HTTP
    MCP_HTTP -->|routes| Handlers
    MCP_HTTP -->|dynamic| DynHandlers

    Handlers -->|XML-RPC| OdooClient
    DynHandlers -->|invoke| EI_Main
    DynHandlers -->|invoke| SimpleAgent
    DynHandlers -->|invoke| DocsProc

    OdooClient -->|CRUD calls| OdooDB
    ModelDisc --> OdooClient
    CRUDGen --> OdooClient
    FieldAnal --> OdooClient
    NLPAnal --> OdooClient

    DocsProc --> EmbEngine
    DocsProc --> DocsRet
    EmbEngine --> EmbDB
    DocsRet --> FaissIdx
    Summarizer -->|calls| OnlineSearch

    EI_Main --> EI_Export
    EI_Main --> EI_Import
    EI_Export --> ExportFS
    EI_Import --> ExportFS

    SimpleAgent -->|generate| ExportFS
    SimpleAgent -->|store| ExportFS

    %% Return flows
    OdooClient -->|response| Handlers
    DocsProc -->|summary| Handlers
    EI_Main -->|status| Handlers
    SimpleAgent -->|code modules| Handlers

    Handlers -->|HTTP/STDIO| StreamlitUI
    Handlers -->|HTTP/STDIO| CLI

    %% Click Events
    click StreamlitUI "https://github.com/infovpcs/odoo18_mcp_project/tree/master/src/streamlit_client/"
    click CLI "https://github.com/infovpcs/odoo18_mcp_project/blob/master/scripts/dynamic_data_tool.py"
    click Claude "https://github.com/infovpcs/odoo18_mcp_project/blob/master/claude_config.json"
    click MCP_HTTP "https://github.com/infovpcs/odoo18_mcp_project/blob/master/mcp_server.py"
    click MCP_STD "https://github.com/infovpcs/odoo18_mcp_project/blob/master/standalone_mcp_server.py"
    click Handlers "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/mcp/handlers.py"
    click DynHandlers "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/mcp/dynamic_handlers.py"
    click MCPClient "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/mcp/client.py"
    click OdooClient "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo/client.py"
    click ModelDisc "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo/dynamic/model_discovery.py"
    click CRUDGen "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo/dynamic/crud_generator.py"
    click FieldAnal "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo/dynamic/field_analyzer.py"
    click NLPAnal "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo/dynamic/nlp_analyzer.py"
    click Schemas "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo/schemas.py"
    click DocsProc "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo_docs_rag/docs_processor.py"
    click DocsRet "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo_docs_rag/docs_retriever.py"
    click EmbEngine "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo_docs_rag/embedding_engine.py"
    click Summarizer "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo_docs_rag/gemini_summarizer.py"
    click OnlineSearch "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo_docs_rag/online_search.py"
    click DBStorage "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/odoo_docs_rag/db_storage.py"
    click SimpleAgent "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/simple_odoo_code_agent/odoo_code_generator.py"
    click DeepWiki "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/simple_odoo_code_agent/utils/deepwiki_client.py"
    click FileSaver "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/simple_odoo_code_agent/utils/file_saver.py"
    click EI_Main "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/agents/export_import/main.py"
    click EI_Export "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/agents/export_import/nodes/export_nodes.py"
    click EI_Import "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/agents/export_import/nodes/import_nodes.py"
    click EI_State "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/agents/export_import/state.py"
    click EI_CSV "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/agents/export_import/utils/csv_handler.py"
    click EI_Map "https://github.com/infovpcs/odoo18_mcp_project/blob/master/src/agents/export_import/utils/field_mapper.py"
    click DockerfileNode "https://github.com/infovpcs/odoo18_mcp_project/tree/master/Dockerfile"
    click Compose "https://github.com/infovpcs/odoo18_mcp_project/blob/master/docker-compose.yml"
    click Env "https://github.com/infovpcs/odoo18_mcp_project/blob/master/.env.example"
    click MakefileNode "https://github.com/infovpcs/odoo18_mcp_project/tree/master/Makefile"

    %% Styles
    classDef ui fill:#D0E7FF,stroke:#0066CC,color:#004C99;
    classDef server fill:#D6F5D6,stroke:#33AA33,color:#1A662A;
    classDef ext fill:#FFE5CC,stroke:#FF9933,color:#CC6600;
    classDef storage fill:#EEEEEE,stroke:#888888,color:#555555;
    classDef db fill:#FFFFFF,stroke:#888888,color:#555555,stroke-dasharray: 5 5;
    classDef infra fill:#F2F2F2,stroke:#999999,color:#666666;
```
