gateway/modules/MODULE_DEPENDENCIES.md

Module Dependencies Analysis

This document provides a comprehensive analysis of import dependencies between modules in the modules directory.

Overview

The codebase is organized into the following top-level modules:

• aicore - AI core functionality and model management
• auth - High-level authentication and token management
• connectors - External service connectors
• datamodels - Data models and schemas
• features - Feature modules (workflow, dynamicOptions, etc.)
• interfaces - Database and service interfaces
• routes - API route handlers
• security - Low-level core security (RBAC and root access)
• services - Business logic services
• shared - Shared utilities and helpers
• workflows - Workflow processing and management

Bidirectional Dependency Matrix

This table shows all module pairs with dependencies, displaying imports in both directions.

Module X	Module Y	X → Y	Y → X	Total
aicore	connectors	1	0	1
aicore	datamodels	13	0	13
aicore	interfaces	0	2	2
aicore	security	2	0	2
aicore	services	0	2	2
aicore	shared	5	0	5
auth	datamodels	5	0	5
auth	interfaces	4	0	4
auth	routes	0	32	32
auth	security	4	0	4
auth	services	0	1	1
auth	shared	8	0	8
connectors	datamodels	4	0	4
connectors	interfaces	0	10	10
connectors	shared	5	0	5
datamodels	features	0	6	6
datamodels	interfaces	0	27	27
datamodels	routes	0	48	48
datamodels	security	0	5	5
datamodels	services	0	52	52
datamodels	shared	19	0	19
datamodels	workflows	0	72	72
features	interfaces	0	0	0
features	routes	0	6	6
features	services	4	0	4
features	shared	3	0	3
features	workflows	1	0	1
interfaces	routes	0	29	29
interfaces	security	9	0	9
interfaces	services	0	8	8
interfaces	shared	11	0	11
routes	interfaces	29	0	29
routes	services	5	0	5
routes	shared	21	0	21
security	connectors	2	0	2
security	datamodels	5	0	5
services	shared	16	0	16
services	workflows	0	1	1
shared	workflows	0	9	9

Legend:

• X → Y: Number of imports from Module X to Module Y
• Y → X: Number of imports from Module Y to Module X
• Total: Sum of imports in both directions

Bidirectional Dependencies Only (Circular Dependencies)

This table shows only module pairs where imports exist in both directions, indicating potential circular dependencies that should be monitored.

Module X	Module Y	X → Y	Y → X	Total

Total bidirectional dependencies: 0

Note: All circular dependencies have been eliminated. The architecture now has clean one-way dependencies.

Key Improvements:

1. Eliminated connectors ↔ security circular dependency: After moving RBAC logic from connectorDbPostgre.py to interfaces/interfaceRbac.py, connectors no longer import from security. Security still imports from connectors (for rootAccess to create DatabaseConnector instances), but this is a one-way dependency (security → connectors: 2, connectors → security: 0).
2. Eliminated shared ↔ security circular dependency: Moved rbacHelpers.py from shared to security module since it was only used in aicore and aicore already imports from security. This eliminates the architectural violation where shared imported from security.
3. Eliminated datamodels ↔ shared circular dependency: shared no longer has any static imports from datamodels. The only reference is a dynamic import in attributeUtils.py using importlib.import_module() for runtime model discovery, which is not detected by static analysis. This is acceptable as it's a runtime-only dependency.
4. New interfaces/interfaceRbac.py module: Created to handle RBAC filtering for interfaces, importing from both security and connectors. This maintains proper architectural layering where connectors remain generic.
5. Updated dependency counts:
   • interfaces → connectors: increased from 9 to 10 (interfaceRbac imports connectorDbPostgre)
   • interfaces → security: increased from 7 to 9 (interfaceRbac imports rbac and rootAccess)
   • features → interfaces: increased from 1 to 2 (mainWorkflow imports interfaceRbac)
   • routes → interfaces: increased from 28 to 29 (routeWorkflows imports interfaceRbac)
   • aicore → security: increased from 1 to 2 (now imports rbacHelpers from security)
   • security → datamodels: increased from 3 to 5 (rbacHelpers adds datamodel imports)

Dependency Graph (Mermaid)

graph TD
    aicore[aicore]
    auth[auth]
    connectors[connectors]
    datamodels[datamodels]
    features[features]
    interfaces[interfaces]
    routes[routes]
    security[security]
    services[services]
    shared[shared]
    workflows[workflows]
    
    aicore -->|13| datamodels
    aicore -->|1| connectors
    aicore -->|2| security
    aicore -->|5| shared
    
    auth -->|5| datamodels
    auth -->|4| interfaces
    auth -->|4| security
    auth -->|8| shared
    
    connectors -->|4| datamodels
    connectors -->|5| shared
    
    datamodels -->|19| shared
    
    features -->|6| datamodels
    features -->|0| interfaces
    features -->|4| services
    features -->|3| shared
    features -->|1| workflows
    
    interfaces -->|29| datamodels
    interfaces -->|10| connectors
    interfaces -->|2| aicore
    interfaces -->|9| security
    interfaces -->|11| shared
    
    routes -->|48| datamodels
    routes -->|29| interfaces
    routes -->|32| auth
    routes -->|21| shared
    routes -->|6| features
    routes -->|5| services
    
    security -->|5| datamodels
    security -->|2| connectors
    security -->|1| shared
    
    services -->|52| datamodels
    services -->|8| interfaces
    services -->|2| aicore
    services -->|1| auth
    services -->|16| shared
    
    
    workflows -->|72| datamodels
    workflows -->|1| services
    workflows -->|9| shared

Detailed Module Dependencies

aicore

Imports from:

• connectors (1 import)
• datamodels (13 imports)
• security (2 imports: rbac, rbacHelpers)
• shared (4 imports)

Dependencies: Low-level AI functionality, depends on data models and connectors.

auth

Imports from:

• datamodels (5 imports)
• interfaces (4 imports)
• security (4 imports)
• shared (8 imports)

Dependencies: High-level authentication and token management, used by routes and services.

connectors

Imports from:

• datamodels (4 imports)
• shared (5 imports)

Dependencies: External service connectors, minimal dependencies. No longer imports from security or interfaces. Connectors are now fully generic and do not depend on security modules.

datamodels

Imports from:

• shared (19 imports)

Dependencies: Core data models, only depends on shared utilities.

features

Imports from:

• datamodels (6 imports)
• services (4 imports)
• shared (3 imports)
• workflows (1 import)

Dependencies: Feature modules that orchestrate workflows and services. Features now use services exclusively, not interfaces directly, maintaining proper architectural layering.

interfaces

Imports from:

• aicore (2 imports)
• connectors (10 imports)
• datamodels (29 imports)
• security (9 imports)
• shared (11 imports)

Dependencies: Database and service interfaces, heavily depends on data models. Includes interfaceRbac.py which handles RBAC filtering for all interfaces. No longer creates circular dependency with connectors.

routes

Imports from:

• auth (32 imports)
• datamodels (48 imports)
• features (6 imports)
• interfaces (29 imports)
• services (5 imports)
• shared (21 imports)

Dependencies: API endpoints, highest dependency count, orchestrates all layers. Now imports from auth instead of security for authentication. Increased use of services (from 2 to 5 imports) after architectural refactoring to use services instead of direct interface access in features.

security

Imports from:

• connectors (2 imports)
• datamodels (5 imports: rbac uses 3, rbacHelpers uses 2)
• shared (1 import: rootAccess uses configuration)

Dependencies: Low-level core security (RBAC, root access, and RBAC helper functions). Used by interfaces (including interfaceRbac.py), auth, and aicore. The rbacHelpers module was moved from shared to security to eliminate the architectural violation where shared imported from security. Security imports from connectors only for rootAccess to create DatabaseConnector instances - this is acceptable as it's a one-way dependency (security → connectors).

services

Imports from:

• aicore (2 imports)
• auth (1 import)
• datamodels (52 imports)
• interfaces (8 imports)
• shared (16 imports)

Dependencies: Business logic services, heavily depends on data models.

shared

Imports from:

• None (0 imports)

Dependencies: Shared utilities, completely self-contained with no dependencies on other modules. No longer imports from security (rbacHelpers was moved to security module) or datamodels (only uses dynamic imports at runtime for model discovery in attributeUtils.py), maintaining proper architectural layering.

workflows

Imports from:

• datamodels (72 imports)
• services (1 import)
• shared (9 imports)

Dependencies: Workflow processing, heavily depends on data models (highest count). Reduced from 74 to 72 imports after removing unused imports from contentValidator.py.

Key Observations

1. datamodels is the most imported module (used by 9 out of 11 modules)
2. shared is widely used but has minimal dependencies (good design)
3. routes has the most diverse dependencies (imports from 6 different modules)
4. workflows has the highest number of imports from datamodels (72)
5. auth is now a separate module, used exclusively by routes and services
6. security is now a low-level module, used by interfaces (including interfaceRbac.py)
7. connectors are now fully generic - no dependencies on security or interfaces
8. Circular dependencies eliminated: Reduced from 3 to 0 after RBAC refactoring and rbacHelpers move (eliminated connectors ↔ security, shared ↔ security, and datamodels ↔ shared)
9. New interfaceRbac.py module centralizes RBAC filtering logic for all interfaces
10. shared module is now completely self-contained - no static imports from any other module
11. Features architectural improvements: Features no longer import directly from interfaces (reduced from 2 to 0). All features now use services exclusively, maintaining proper layering: Features → Services → Interfaces → Connectors
12. Routes increased services usage: Routes now import from services 5 times (up from 2) after refactoring features to use services instead of direct interface access

Dependency Layers

Based on the analysis, the architecture follows these layers:

1. Foundation Layer: shared, datamodels
2. Core Layer: aicore, connectors, security
3. Interface Layer: interfaces
4. Authentication Layer: auth
5. Business Logic Layer: services, workflows
6. Feature Layer: features
7. API Layer: routes

Recommendations

1. datamodels should remain stable as it's a core dependency
2. shared is excellently designed - completely self-contained with zero dependencies (perfect foundation layer)
3. security split and RBAC refactoring were successful - eliminated all circular dependencies (connectors ↔ security, shared ↔ security)
4. connectors are now fully generic and maintainable - keep them free of security/interface dependencies
5. interfaceRbac.py successfully centralizes RBAC logic - consider this pattern for other cross-cutting concerns
6. Consider breaking down workflows if it continues to grow
7. routes could benefit from further abstraction to reduce direct dependencies
8. Architecture is now clean - no circular dependencies remain, maintaining clear separation of concerns