Architecture

The OCI Policy Analysis tool has the following overall architecture:

Overall Architecture

Each tier works together to form a clean separation between presentation, data repository, and associated tools and helpers. Third-party projects, such as DeepDiff, are used for comparisons, and FastMCP is used to expose MCP to clients. All access to OCI is via the OCI official Python SDK and the supported tenancy configurations.

Data Model

The data model starts as an empty JSON object and is then populated by API calls via the OCI SDK, describing compartments, IAM identities, and policies. The data model captures structure, effective permissions, parsed/derived fields (like effective path or validity), and more.

        flowchart TD
    A[Tenancy] --> B[Compartment Hierarchy]
    B --> C[Policies]
    C --> D[Effective Permissions
    Validity
    Parsing]
    A --> E[Users / Groups / Dynamic Groups]
    C --> R[Policy Repo]
    D --> R
    E --> R
    R --> F[User Interface + AI Insights]
    R --> M[MCP Server]
    R --> CL[Command Line]

Layers

Data Layer
Loads, caches, parses, and normalizes tenancy data including policies, users, groups, and dynamic groups. Provides efficient queries on the in-memory model.

Intelligence Layer
Derives additional analytics and insights, such as policy recommendations, cleanup tasks, security risks, and overlap/consolidation suggestions.

MCP Layer
Runs an embedded MCP server using FastMCP to expose the current policy state and analytics as tools/resources to compatible clients.

UI Layer
Implements all user-visible tabs, resizable panes, and integrates with the full policy/data model and analytics overlays.

Policy Parsing

OCI policies are parsed using a dedicated ANTLR-based parser, which incorporates a comprehensive grammar covering the full breadth of OCI Policy Syntax. The parser translates written policy statements into well-structured parse trees, enabling detailed, robust extraction of policy components, conditions, and rules.

Once a policy statement is parsed, a series of derived fields are computed and added to the internal data model:

Effective Path: Determines which compartments a statement is in scope for, based on the policy’s compartment location and referenced locations within statements.
Validity & Invalid Reasons: Calculates if a policy statement is internally consistent and matches live OCI structures (e.g., references to deleted compartments or malformed subjects).
Parsed Conditions and Statement Breakdown: Conditionals (WHERE clauses), operators, and subjects are normalized and attached to the data model for fine-grained filtering and analysis.
Policy Overlap: Leveraging resource-to-permission data, the system computes which statements overlap in their effective permissions, enabling conflict/duplication analysis.
Canonical Models: All parsed data is mapped to strict TypedDict-based schemas, powering consistent filtering, UI rendering, and MCP responses.

The ANTLR grammar and parser implementation ensure that all features and edge cases in the evolving OCI policy language are handled with a high degree of accuracy. See CONTEXT_logic.md and CONTEXT_policies_tab.md for technical and tab-specific integration details.

Caching

The application persistently caches full tenancy analyses (IAM, policies, derived fields, overlays) as versioned JSON files. Caching serves to:

Accelerate reloads (especially when analyzing large tenancies or when OCI credentials are not immediately available)
Support offline/remote diagnostics or hand-offs
Provide input for diff/historical comparison functionality

The cache format reflects the canonical data model and overlays as computed at data load time. All filtering, policy intelligence, and tab workflows can operate seamlessly over in-memory or cached data; the data repository manages de-duplication and versioning.

Cache management includes import, export, snapshotting, refreshing, and selection of caches—all directly exposed via the Settings Tab. See CONTEXT_data_repo.md and CONTEXT_settings_tab.md for more details.

Settings

A robust and extensible settings system governs configuration for all areas of the application. Settings management covers:

Tenancy/OCI configuration (profile, session token, compartment selection, recursion, GenAI model selection, MCP server config)
UI preferences (font size, tab visibility, context help, advanced tab enablement)
Cache import/export, refresh, and selection
Application-wide toggles for maintenance/debug features

Settings are saved and loaded automatically to persistent storage, enabling reproducibility between sessions. The settings system ensures all tabs receive relevant configuration updates dynamically, leveraging a propagation mechanism orchestrated by the main UI controller.

See CONTEXT_settings_tab.md for full architectural overview and field-by-field design.

Logging

Logging is centrally managed by a flexible, unified system supporting global and per-component log levels, controlled both at startup and dynamically via the Console Tab UI. Key characteristics:

Log messages from all components go both to the shell and to a persistently-rotated application logfile.
In-app Console Tab shows INFO+ logs for all components, while the shell and log file can include DEBUG-level output per logger.
Log level selection is fully dynamic, can target individual loggers, and is instantly persisted for the next session.
Special modes (like CLI --verbose) override all levels and pin logging for troubleshooting.
ConsoleTab UI cannot enable global DEBUG logging, only component-level.

See CONTEXT_logging.md for architecture diagrams, detailed workflows, and UI patterns.

Feature/Tab Architecture & Context File Reference

The following context files document the architecture, design patterns, and history for each major feature, tab, or engineering workflow. Use these files as the authoritative references for any technical question, refactor, or implementation detail.

Generic context:

GENERIC_README: Universal project documentation patterns and starter guidance.
GENERIC_UI_GUIDELINES: Generic UI/UX standards for tab layout, naming, and interactions.
GENERIC_CODING_STANDARDS: Foundational code quality, formatting, and structural requirements.

Project-specific context (with coverage summaries):

CONTEXT_cli.md: Design, options, and usage of the Command Line Interface (CLI) for policy analysis.
CONTEXT_config.md: Rules and best practices for repository configuration and code quality automation.
CONTEXT_cross_tenancy.md: How cross-tenancy statements are modeled, filtered, and displayed in the Cross Tenancy Tab.
CONTEXT_data_repo.md: Core architecture for canonical data models, repository logic, and persistent caching.
CONTEXT_docs.md: Documentation standards and practices unique to this repository.
CONTEXT_historical_analysis.md: Architecture, flow, and UX conventions for the Historical Comparison Tab (policy/IAM diffs over time).
CONTEXT_intelligence_strategies.md: The strategy pattern and pluggable modules powering analytics and recommendations.
CONTEXT_logging.md: Logging architecture, configuration, UI/console separation, and DEBUG/per-component controls.
CONTEXT_logic.md: Business/processing logic layer structure, parsing system, and testability standards.
CONTEXT_mcp_server_and_tab.md: MCP server architecture and how it integrates with the UI’s Embedded MCP Tab.
CONTEXT_policies_tab.md: Details for the UI Policies Tab, including table layouts, filters, parsing flows, and sorting conventions.
CONTEXT_policy_browser_tab.md: Patterns and architecture for the Policy Browser Tab (hierarchical tree view).
CONTEXT_policy_intelligence_and_recommendations.md: How analytics overlays and cleanup/fix/recommendations are produced and surfaced in the Recommendations Tab.
CONTEXT_settings_tab.md: Architecture and features managed by the Settings Tab, including configuration fields, cache management, and UI control propagation.
CONTEXT_simulation_engine.md: Simulation engine data flows, models, and automation for the API Simulation/Condition Tester tabs.
CONTEXT_tests.md: Required test practices, edge cases, and integration with CI/CD and pre-commit.
CONTEXT_ui.md: UI layer conventions, tab base class, context help/patterns, and registration requirements.

For any new feature or major tab, start by documenting its rationale and conventions in a new or updated context file below docs/context/project/.

For detailed table of contents and links to all supporting context files, see above and the CONTEXT_INDEX.md.

Core Runtime Architecture (4 Consumer Paths)

The codebase exposes a shared core through four primary consumer paths:

Desktop UI (main.py / Tkinter tabs)
CLI (cli.py)
Web API (web/api/routes_core.py via FastAPI dependencies)
MCP Server (mcp_server.py via FastMCP)

Each path ultimately converges on shared repository and engine components, with OCI SDK and supporting platform services beneath the core domain.

Runtime Flow (Consumers to Engines)

        flowchart TB
    subgraph C[Consumer Paths]
        direction TB
        UI["Desktop UI<br/>main.py"]
        WEB["Web API<br/>routes_core.py"]
        CLI["CLI<br/>cli.py"]
        MCP["MCP Server<br/>mcp_server.py"]
    end

    subgraph A[Application Orchestration]
        direction TB
        CTX["AppContext<br/>shared runtime context"]
        SVC["Application Services<br/>load and analysis orchestration"]
    end

    subgraph D[Core Domain Execution]
        direction TB
        REPO["PolicyAnalysisRepository"]
        INTEL["PolicyIntelligenceEngine"]
        SIM["PolicySimulationEngine"]
        CONS["ConsolidationEngine"]
    end

    UI --> CTX
    WEB --> CTX
    CLI --> SVC
    MCP --> SVC
    CTX --> SVC

    SVC --> REPO
    SVC --> INTEL
    SVC --> SIM
    SVC --> CONS

    INTEL --> REPO
    SIM --> REPO
    CONS --> REPO

Logical Layering (Domain, Models, Platform, External)

        flowchart TB
    subgraph D[Core Domain Layer]
        direction TB
        REPO["PolicyAnalysisRepository<br/>canonical in-memory policy and IAM model"]
        REF["ReferenceDataRepo<br/>permission and resource references"]
        PARSER["ANTLR Parser and Normalizer<br/>parse, validate, derive fields"]
    end

    subgraph M[Models Tier]
        direction TB
        MODEL_POLICY["Policy Models<br/>BasePolicy, Regular and Cross-Tenancy statements"]
        MODEL_IAM["IAM Models<br/>User, Group, Dynamic Group, Compartment"]
        MODEL_SIM["Simulation Models<br/>Scenario, Result, Prospective Statement"]
        MODEL_RESP["Response Models<br/>Filter, Summary, Diff, API payloads"]
    end

    subgraph P[Platform Services]
        direction TB
        CFG["Settings and Config"]
        CACHE["CacheManager"]
        LOG["Logging System"]
        TRACK["Usage Tracking"]
    end

    subgraph X[External Sources and Sinks]
        direction TB
        OCI["OCI Python SDK"]
        CIS["CIS Compliance CSV Output"]
        OBJ["Object Storage Bucket<br/>usage tracking artifacts"]
    end

    D --> M
    M --> P
    P --> X

    REPO --> PARSER
    REPO --> REF
    REPO --> MODEL_POLICY
    REPO --> MODEL_IAM
    REPO --> MODEL_SIM
    REPO --> MODEL_RESP

    REPO --> OCI
    REPO --> CIS
    CFG --> CACHE
    CFG --> LOG
    TRACK --> OBJ

Cross-Cutting Operations (Settings, Logging, Usage)

        flowchart TB
    subgraph Consumers
        direction TB
        UI["Desktop UI"]
        WEB["Web API"]
        CLI["CLI"]
        MCP["MCP Server"]
    end

    subgraph Platform
        direction TB
        CFG["Settings and Config"]
        LOG["Logging System"]
        TRACK["Usage Tracking"]
        CACHE["CacheManager"]
    end

    OBJ["Object Storage Bucket"]

    UI --> CFG
    WEB --> CFG
    CLI --> CFG
    MCP --> CFG

    UI --> LOG
    WEB --> LOG
    CLI --> LOG
    MCP --> LOG

    UI --> TRACK
    WEB --> TRACK
    CLI --> TRACK
    MCP --> TRACK

    CFG --> CACHE
    TRACK --> OBJ