292 lines
12 KiB
Markdown
292 lines
12 KiB
Markdown
# 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
|