# 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)

```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