# yazeedmshayekh2/corereports architecture

> Architecture diagram of the GitHub repository yazeedmshayekh2/corereports, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yazeedmshayekh2/corereports
- Repository: https://github.com/yazeedmshayekh2/corereports

## Overview

1. **Repository shape**
   - This is an AI assistant for insurance data analysis, split into a **web/chat UI**, a **core orchestration layer**, an **agent layer**, an **AI model layer**, and an **Oracle database layer**.
   - It also includes a **CLI/interactive mode**, so the same intelligence system can be used both from a browser and from the command line.

2. **User-facing presentation layer**
   - `frontend/templates/chatbot.html` plus `frontend/static/js/chatbot.js` and `frontend/static/css/chatbot.css` form the chat interface.
   - The browser UI is responsible for capturing user prompts, rendering responses, and likely handling streaming/progressive output from the backend.

3. **Application entrypoints**
   - `src/K2/app.py` is the main application entrypoint for the runnable system.
   - `src/K2/aims_view/core/main.py` provides the non-web entrypoint for interactive/demo CLI usage.
   - This suggests two execution paths that converge on the same orchestration and agent stack.

4. **Central orchestration boundary**
   - `src/K2/aims_view/agents/intelligence_manager.py` is the main coordination layer.
   - It acts as the brain of the system, deciding which agents to invoke, in what order, and when to retry or refine a query.
   - The readme describes multi-cycle problem solving, strategic planning, execution, and streaming response generation as key behaviors here.

5. **Intelligence agent pipeline**
   - The core agent set under `agents/intelligence/` represents a staged reasoning workflow:
     - `strategic_planner.py` decides the approach.
     - `schema_analyst.py` inspects database structure.
     - `query_architect.py` designs SQL.
     - `execution_specialist.py` runs the query.
     - `computational_analyst.py` performs calculations/analytics.
     - `results_evaluator.py` checks output quality.
     - `response_generator.py` turns results into a final answer.
   - Architecturally, this is a pipeline from natural language to structured database action to final response.

6. **Specialized entity-resolution layer**
   - `agents/specialized/` contains support agents for customer/name handling:
     - `name_detector.py`
     - `customer_validator.py`
     - `name_matcher.py`
   - These likely resolve user mentions to real insurance customer records before query execution, which is important for accuracy in domain-specific conversations.

7. **AI/LLM infrastructure**
   - `src/K2/aims_view/ai/llm_factory.py` centralizes creation of model clients.
   - The readme indicates the system uses **Gemini 2.5 Flash** and **Groq LLaMA 3.3 70B**, with streaming support.
   - `security/ssl_config.py` provides enterprise SSL-bypass configuration, which is an infrastructure concern rather than business logic.

8. **Domain knowledge and prompt/context assembly**
   - `core/domain_knowledge.py` is a key boundary: it contains AIMS-specific insurance knowledge, field patterns, business rules, organizational structure, and calculation logic.
   - `utils/context_builder.py` and `utils/query_utils.py` turn that knowledge into usable prompt/context material and clean/validate SQL.
   - This means the system is not just LLM-driven; it is grounded by explicit domain rules.

9. **Database access layer**
   - `src/K2/aims_view/database/database.py` is the Oracle integration layer.
   - The readme and docs indicate environment-based Oracle credentials and service settings, so the assistant depends on an external Oracle database for actual business data.
   - The architecture implies a strict boundary: agents generate or refine SQL, while the database module owns connection/execution details.

10. **Conversation state and memory**
   - `memory/conversation_memory.json` stores conversation history or session memory.
   - `utils/memory_utils.py` likely manages reading/writing or formatting that memory for context reuse.
   - This persistence layer supports follow-up questions and multi-turn reasoning.

11. **Security and operational concerns**
   - The readme calls out input validation, sanitization, SQL injection prevention, rate limiting, and logging.
   - In architectural terms, these are cross-cutting controls wrapping the query-generation and database-execution path, not separate business features.

12. **Configuration and runtime dependencies**
   - `config.json` holds system configuration for models, cycles/thresholds, agent behavior, and database settings.
   - External runtime dependencies are important here: the app needs API keys for Gemini and Groq, plus Oracle connection variables.
   - So the system is effectively a coordinated service that bridges **UI input → AI reasoning → Oracle data retrieval → natural-language response**.

Main entry points: [`src/K2/aims_view/agents/intelligence_manager.py`](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence_manager.py) (Intelligence Manager), [`src/K2/aims_view/agents/intelligence/strategic_planner.py`](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/strategic_planner.py) (Planner), [`src/K2/aims_view/agents/intelligence/execution_specialist.py`](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/execution_specialist.py) (Execution Specialist), [`frontend/static/js/chatbot.js`](https://github.com/yazeedmshayekh2/corereports/blob/main/frontend/static/js/chatbot.js) (Chat JS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["UI"]
  node_node_chat_ui["Chat UI<br/>web template<br/>[chatbot.html]"]
  node_node_chat_js["Chat JS<br/>frontend logic<br/>[chatbot.js]"]
  node_node_chat_css["Chat CSS<br/>presentation<br/>[chatbot.css]"]
end

subgraph group_group_entry["Entrypoints"]
  node_node_web_app["Web App<br/>entrypoint<br/>[app.py]"]
  node_node_cli_main["CLI Main<br/>entrypoint<br/>[main.py]"]
  node_node_interactive["Interactive<br/>cli runner<br/>[interactive.py]"]
end

subgraph group_group_orchestration["Orchestration"]
  node_node_manager{{"Intelligence Manager<br/>orchestrator"}}
  node_node_domain["Domain Knowledge<br/>rules & context"]
  node_node_context["Context Builder<br/>prompt assembly<br/>[context_builder.py]"]
  node_node_memory_utils["Memory Utils<br/>session helper<br/>[memory_utils.py]"]
end

subgraph group_group_agents["Agents"]
  node_node_planner["Planner<br/>agent"]
  node_node_schema["Schema Analyst<br/>agent<br/>[schema_analyst.py]"]
  node_node_query["Query Architect<br/>agent<br/>[query_architect.py]"]
  node_node_exec["Execution Specialist<br/>agent"]
  node_node_calc["Computational Analyst<br/>agent"]
  node_node_eval["Results Evaluator<br/>agent"]
  node_node_response["Response Generator<br/>agent"]
  node_node_name_detector["Name Detector<br/>specialized agent<br/>[name_detector.py]"]
  node_node_customer_validator["Customer Validator<br/>specialized agent"]
  node_node_name_matcher["Name Matcher<br/>specialized agent<br/>[name_matcher.py]"]
end

subgraph group_group_infra["Infra"]
  node_node_llm["LLM Factory<br/>model gateway<br/>[llm_factory.py]"]
  node_node_db[("Oracle DB<br/>database gateway<br/>[database.py]")]
  node_node_ssl["SSL Config<br/>security config<br/>[ssl_config.py]"]
  node_node_config["Config<br/>[config.json]"]
  node_node_memory["Conversation Memory<br/>session store"]
end

node_node_web_app -->|"serves"| node_node_chat_ui
node_node_chat_js -->|"sends prompts"| node_node_manager
node_node_cli_main -->|"launches"| node_node_interactive
node_node_interactive -->|"invokes"| node_node_manager
node_node_manager -->|"builds context"| node_node_context
node_node_context -->|"uses"| node_node_domain
node_node_manager -->|"reads/writes"| node_node_memory_utils
node_node_memory_utils -->|"stores"| node_node_memory
node_node_manager -->|"starts with"| node_node_planner
node_node_planner -->|"checks entities"| node_node_name_detector
node_node_name_detector -->|"validates"| node_node_customer_validator
node_node_customer_validator -->|"resolves"| node_node_name_matcher
node_node_planner -->|"routes to"| node_node_schema
node_node_schema -->|"informs"| node_node_query
node_node_query -->|"executes via"| node_node_exec
node_node_exec -->|"queries"| node_node_db
node_node_exec -->|"passes results"| node_node_calc
node_node_calc -->|"reviews"| node_node_eval
node_node_eval -->|"finalizes"| node_node_response
node_node_manager -->|"uses models"| node_node_llm
node_node_llm -->|"reads settings"| node_node_config
node_node_db -->|"secures"| node_node_ssl
node_node_manager -->|"reads settings"| node_node_config
node_node_chat_js -->|"renders"| node_node_response

click node_node_chat_ui "https://github.com/yazeedmshayekh2/corereports/blob/main/frontend/templates/chatbot.html"
click node_node_chat_js "https://github.com/yazeedmshayekh2/corereports/blob/main/frontend/static/js/chatbot.js"
click node_node_chat_css "https://github.com/yazeedmshayekh2/corereports/blob/main/frontend/static/css/chatbot.css"
click node_node_web_app "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/app.py"
click node_node_cli_main "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/core/main.py"
click node_node_interactive "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/core/interactive.py"
click node_node_manager "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence_manager.py"
click node_node_domain "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/core/domain_knowledge.py"
click node_node_context "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/utils/context_builder.py"
click node_node_memory_utils "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/utils/memory_utils.py"
click node_node_planner "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/strategic_planner.py"
click node_node_schema "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/schema_analyst.py"
click node_node_query "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/query_architect.py"
click node_node_exec "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/execution_specialist.py"
click node_node_calc "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/computational_analyst.py"
click node_node_eval "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/results_evaluator.py"
click node_node_response "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/response_generator.py"
click node_node_name_detector "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/specialized/name_detector.py"
click node_node_customer_validator "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/specialized/customer_validator.py"
click node_node_name_matcher "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/specialized/name_matcher.py"
click node_node_llm "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/ai/llm_factory.py"
click node_node_db "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/database/database.py"
click node_node_ssl "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/security/ssl_config.py"
click node_node_config "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/config.json"
click node_node_memory "https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/memory/conversation_memory.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_chat_ui,node_node_chat_js,node_node_chat_css toneBlue
class node_node_web_app,node_node_cli_main,node_node_interactive toneAmber
class node_node_manager,node_node_domain,node_node_context,node_node_memory_utils toneMint
class node_node_planner,node_node_schema,node_node_query,node_node_exec,node_node_calc,node_node_eval,node_node_response,node_node_name_detector,node_node_customer_validator,node_node_name_matcher toneRose
class node_node_llm,node_node_db,node_node_ssl,node_node_config,node_node_memory toneIndigo
```

## Components

### UI

Browser-facing chat interface and client-side behavior.

- [Chat UI](https://github.com/yazeedmshayekh2/corereports/blob/main/frontend/templates/chatbot.html): web template · Browser chat surface for user prompts and responses. · `frontend/templates/chatbot.html`
- [Chat JS](https://github.com/yazeedmshayekh2/corereports/blob/main/frontend/static/js/chatbot.js): frontend logic · Client-side interaction, request handling, and streaming response updates. · `frontend/static/js/chatbot.js`
- [Chat CSS](https://github.com/yazeedmshayekh2/corereports/blob/main/frontend/static/css/chatbot.css): presentation · Visual styling for the chat interface. · `frontend/static/css/chatbot.css`

### Entrypoints

Web and CLI startup paths that converge on the same core system.

- [Web App](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/app.py): entrypoint · Main runnable application entry for the browser-based system. · `src/K2/app.py`
- [CLI Main](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/core/main.py): entrypoint · Non-web interactive/demo entry path. · `src/K2/aims_view/core/main.py`
- [Interactive](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/core/interactive.py): cli runner · Console interaction loop and demo-style usage flow. · `src/K2/aims_view/core/interactive.py`

### Orchestration

Central coordination, state, and domain-aware prompt assembly.

- [Intelligence Manager](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence_manager.py): orchestrator · Central coordination layer that plans cycles, routes work, and assembles responses. · `src/K2/aims_view/agents/intelligence_manager.py`
- [Domain Knowledge](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/core/domain_knowledge.py): rules & context · Insurance-specific business rules, patterns, and calculation knowledge. · `src/K2/aims_view/core/domain_knowledge.py`
- [Context Builder](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/utils/context_builder.py): prompt assembly · Builds grounded prompt/context from domain knowledge and conversation state. · `src/K2/aims_view/utils/context_builder.py`
- [Memory Utils](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/utils/memory_utils.py): session helper · Formats and persists conversation state for multi-turn reasoning. · `src/K2/aims_view/utils/memory_utils.py`

### Agents

Planning, schema, SQL, execution, analysis, and response generation.

- [Planner](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/strategic_planner.py): agent · Chooses the overall strategy for answering the user. · `src/K2/aims_view/agents/intelligence/strategic_planner.py`
- [Schema Analyst](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/schema_analyst.py): agent · Inspects database structure and relevant entities. · `src/K2/aims_view/agents/intelligence/schema_analyst.py`
- [Query Architect](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/query_architect.py): agent · Designs the SQL query plan from the user request and schema. · `src/K2/aims_view/agents/intelligence/query_architect.py`
- [Execution Specialist](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/execution_specialist.py): agent · Runs the query through the database layer and captures results. · `src/K2/aims_view/agents/intelligence/execution_specialist.py`
- [Computational Analyst](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/computational_analyst.py): agent · Performs calculations and derived analytics on retrieved data. · `src/K2/aims_view/agents/intelligence/computational_analyst.py`
- [Results Evaluator](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/results_evaluator.py): agent · Checks output quality, completeness, and answer fitness. · `src/K2/aims_view/agents/intelligence/results_evaluator.py`
- [Response Generator](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/intelligence/response_generator.py): agent · Turns validated results into the final natural-language answer. · `src/K2/aims_view/agents/intelligence/response_generator.py`
- [Name Detector](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/specialized/name_detector.py): specialized agent · Detects customer or person names in user input. · `src/K2/aims_view/agents/specialized/name_detector.py`
- [Customer Validator](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/specialized/customer_validator.py): specialized agent · Validates mentions against known customer records. · `src/K2/aims_view/agents/specialized/customer_validator.py`
- [Name Matcher](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/agents/specialized/name_matcher.py): specialized agent · Resolves name variants to the most likely insurance customer entity. · `src/K2/aims_view/agents/specialized/name_matcher.py`

### Infra

Model access, database connectivity, security, and persistence.

- [LLM Factory](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/ai/llm_factory.py): model gateway · Creates and configures Gemini and Groq model clients with streaming support. · `src/K2/aims_view/ai/llm_factory.py`
- [Oracle DB](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/database/database.py): database gateway · Oracle connection and query execution boundary for business data access. · `src/K2/aims_view/database/database.py`
- [SSL Config](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/security/ssl_config.py): security config · Enterprise SSL-bypass and connection security settings. · `src/K2/aims_view/security/ssl_config.py`
- [Config](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/config.json): runtime config · System settings for models, cycles, thresholds, agents, and database behavior. · `src/K2/aims_view/config.json`
- [Conversation Memory](https://github.com/yazeedmshayekh2/corereports/blob/main/src/K2/aims_view/memory/conversation_memory.json): session store · Persistent conversation history for follow-up questions and continuity. · `src/K2/aims_view/memory/conversation_memory.json`

## Connections

- Web App → Chat UI: serves · The web entrypoint presents the chat interface.
- Chat JS → Intelligence Manager: sends prompts · Browser interactions invoke the core orchestration layer.
- CLI Main → Interactive: launches · The CLI entry delegates to the interactive runner.
- Interactive → Intelligence Manager: invokes · Interactive sessions call the same orchestration core.
- Intelligence Manager → Context Builder: builds context · Coordinates grounded context for reasoning and response generation.
- Context Builder → Domain Knowledge: uses · Domain knowledge is injected into prompt/context construction.
- Intelligence Manager → Memory Utils: reads/writes · Conversation state is loaded and persisted across turns.
- Memory Utils → Conversation Memory: stores · Persistent session history backing multi-turn conversations.
- Intelligence Manager → Planner: starts with · The manager begins the reasoning cycle with strategic planning.
- Planner → Name Detector: checks entities · Customer-name detection can pre-process user requests.
- Name Detector → Customer Validator: validates · Detected names are checked against customer records.
- Customer Validator → Name Matcher: resolves · Matching disambiguates customer identity.
- Planner → Schema Analyst: routes to · The plan may require schema inspection.
- Schema Analyst → Query Architect: informs · Schema findings guide SQL design.
- Query Architect → Execution Specialist: executes via · Designed queries are handed to execution.
- Execution Specialist → Oracle DB: queries · Database access is isolated in the Oracle layer.
- Execution Specialist → Computational Analyst: passes results · Retrieved rows feed computational analysis.
- Computational Analyst → Results Evaluator: reviews · Derived results are checked for quality and sufficiency.
- Results Evaluator → Response Generator: finalizes · Validated output is converted into the response.
- Intelligence Manager → LLM Factory: uses models · Agent calls are mediated by the model factory.
- LLM Factory → Config: reads settings · Model selection and runtime behavior come from configuration.
- Oracle DB → SSL Config: secures · Connection behavior is shaped by SSL settings.
- Intelligence Manager → Config: reads settings · Execution thresholds and agent behavior come from config.
- Chat JS → Response Generator: renders · Streaming or final responses are shown in the UI.
