# elsayedelmandoh/spaceeye-geoai architecture

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

- Interactive diagram: https://gitdiagram.com/elsayedelmandoh/spaceeye-geoai
- Repository: https://github.com/elsayedelmandoh/spaceeye-geoai

## Overview

SpaceEye ranks coded R7 compounds for committee inspections and presents the results through a Streamlit observatory and hybrid RAG chatbot. The dashboard workflow moves from prepared data to indicator and priority views, then to inspection planning and exports; separate capabilities cover synthetic what-if analysis, early-warning evaluation, imagery context, and guarded inspection reports. The chatbot routes questions, retrieves structured and document evidence, and produces sourced answers, using Gemini within a budget or local generation. Several pipeline and data-preparation links are documented but their implementation was not sampled, so those edges are omitted.

Main entry points: [`app.py`](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/app.py) (Dashboard UI), [`chatbot/app/generation/service.py`](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/generation/service.py) (Answer Service), [`chatbot/app/retrieval/hybrid.py`](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/hybrid.py) (Hybrid Retrieval), [`src/pipeline/setup_review.py`](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/pipeline/setup_review.py) (Prepared Release)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_observatory["Priority Observatory"]
  node_dashboard["Dashboard UI<br/>[app.py]"]
  node_insights["Priority Insights<br/>[insights.py]"]
  node_visit_form["Visit Planning<br/>[ops_visits.py]"]
  node_cycle_export["Cycle CSV Export<br/>[exports.py]"]
  node_prepared_data[("Prepared Release<br/>[setup_review.py]")]
  node_shared_config["Data Paths and Config<br/>[common.py]"]
end

subgraph group_analytics["Analysis and Scenarios"]
  node_ew_features["Warning Features<br/>[ew_features.py]"]
  node_ew_evaluation["Warning Evaluation<br/>[ew_eval.py]"]
  node_scenarios["What-if Scenarios<br/>[scenarios.py]"]
end

subgraph group_evidence["Evidence and Reporting"]
  node_imagery["Satellite Imagery"]
  node_inspection_file["Inspection Context<br/>[inspection_file.py]"]
  node_inspection_report["Guarded Reports"]
end

subgraph group_chat["RAG Chatbot"]
  node_chat_ui["Chat Interface<br/>[app.js]"]
  node_chat_api["Chat API<br/>[main.py]"]
  node_chat_service["Answer Service<br/>[service.py]"]
  node_query_router["Intent Router<br/>[router.py]"]
  node_hybrid_retrieval["Hybrid Retrieval<br/>[hybrid.py]"]
  node_structured_facts[("Structured Facts<br/>[structured.py]")]
  node_vector_search[("Vector Search<br/>[vector_store.py]")]
  node_answer_builder["Local Answer Builder<br/>[answer_builder.py]"]
  node_gemini["Gemini Generation<br/>[gemini_client.py]"]
end

node_committee(("Inspection Committee"))
node_chat_user(("Dashboard Chat User"))

node_committee -->|"views priorities"| node_dashboard
node_dashboard -->|"builds views"| node_insights
node_dashboard -->|"opens form"| node_visit_form
node_dashboard -->|"exports cycle"| node_cycle_export
node_dashboard -.->|"reads release"| node_prepared_data
node_prepared_data -->|"uses paths"| node_shared_config
node_committee -.->|"reviews context"| node_imagery
node_ew_features -->|"supplies features"| node_ew_evaluation
node_committee -.->|"explores what-if"| node_scenarios
node_committee -.->|"uses contexts"| node_inspection_file
node_inspection_file -->|"renders report"| node_inspection_report
node_chat_user -->|"asks question"| node_chat_ui
node_chat_ui -.->|"sends question"| node_chat_api
node_chat_api -->|"processes question"| node_chat_service
node_chat_service -->|"retrieves evidence"| node_hybrid_retrieval
node_hybrid_retrieval -->|"routes query"| node_query_router
node_hybrid_retrieval -->|"reads facts"| node_structured_facts
node_hybrid_retrieval -->|"searches documents"| node_vector_search
node_chat_service -->|"builds local answer"| node_answer_builder
node_chat_service -->|"generates answer"| node_gemini

click node_dashboard "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/app.py"
click node_insights "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/dashboard/insights.py"
click node_visit_form "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/dashboard/ops_visits.py"
click node_cycle_export "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/dashboard/exports.py"
click node_prepared_data "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/pipeline/setup_review.py"
click node_shared_config "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/pipeline/common.py"
click node_imagery "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/pipeline/imagery_earth_engine.py"
click node_ew_features "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/analysis/ew_features.py"
click node_ew_evaluation "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/analysis/ew_eval.py"
click node_scenarios "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/generator/scenarios.py"
click node_inspection_file "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/inference/inspection_file.py"
click node_inspection_report "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/inference/inspection_report.py"
click node_chat_ui "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/frontend/app.js"
click node_chat_api "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/api/main.py"
click node_chat_service "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/generation/service.py"
click node_query_router "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/router.py"
click node_hybrid_retrieval "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/hybrid.py"
click node_structured_facts "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/structured.py"
click node_vector_search "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/vector_store.py"
click node_answer_builder "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/generation/answer_builder.py"
click node_gemini "https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/generation/gemini_client.py"

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_dashboard,node_insights,node_visit_form,node_cycle_export,node_prepared_data,node_shared_config,node_chat_user toneBlue
class node_ew_features,node_ew_evaluation,node_scenarios toneAmber
class node_imagery,node_inspection_file,node_inspection_report toneMint
class node_chat_ui,node_chat_api,node_chat_service,node_query_router,node_hybrid_retrieval,node_structured_facts,node_vector_search,node_answer_builder,node_gemini toneRose
class node_committee toneIndigo
```

## Components

### Priority Observatory

- [Dashboard UI](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/app.py): `app.py`
- [Priority Insights](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/dashboard/insights.py): `src/dashboard/insights.py`
- [Visit Planning](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/dashboard/ops_visits.py): `src/dashboard/ops_visits.py`
- [Cycle CSV Export](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/dashboard/exports.py): `src/dashboard/exports.py`
- [Prepared Release](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/pipeline/setup_review.py): `src/pipeline/setup_review.py`
- [Data Paths and Config](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/pipeline/common.py): `src/pipeline/common.py`

### Analysis and Scenarios

- [Warning Features](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/analysis/ew_features.py): `src/analysis/ew_features.py`
- [Warning Evaluation](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/analysis/ew_eval.py): `src/analysis/ew_eval.py`
- [What-if Scenarios](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/generator/scenarios.py): `src/generator/scenarios.py`

### Evidence and Reporting

- [Satellite Imagery](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/pipeline/imagery_earth_engine.py): `src/pipeline/imagery_earth_engine.py`
- [Inspection Context](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/inference/inspection_file.py): `src/inference/inspection_file.py`
- [Guarded Reports](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/src/inference/inspection_report.py): `src/inference/inspection_report.py`

### RAG Chatbot

- [Chat Interface](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/frontend/app.js): `chatbot/frontend/app.js`
- [Chat API](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/api/main.py): `chatbot/app/api/main.py`
- [Answer Service](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/generation/service.py): `chatbot/app/generation/service.py`
- [Intent Router](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/router.py): `chatbot/app/retrieval/router.py`
- [Hybrid Retrieval](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/hybrid.py): `chatbot/app/retrieval/hybrid.py`
- [Structured Facts](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/structured.py): `chatbot/app/retrieval/structured.py`
- [Vector Search](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/retrieval/vector_store.py): `chatbot/app/retrieval/vector_store.py`
- [Local Answer Builder](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/generation/answer_builder.py): `chatbot/app/generation/answer_builder.py`
- [Gemini Generation](https://github.com/elsayedelmandoh/spaceeye-geoai/blob/main/chatbot/app/generation/gemini_client.py): `chatbot/app/generation/gemini_client.py`

### Other components

- **Inspection Committee**
- **Dashboard Chat User**

## Connections

- Inspection Committee → Dashboard UI: views priorities (evidence: `README.md`)
- Dashboard UI → Priority Insights: builds views (evidence: `app.py`)
- Dashboard UI → Visit Planning: opens form (evidence: `app.py`)
- Dashboard UI → Cycle CSV Export: exports cycle (evidence: `app.py`)
- Dashboard UI → Prepared Release: reads release
- Prepared Release → Data Paths and Config: uses paths (evidence: `src/pipeline/setup_review.py`)
- Inspection Committee → Satellite Imagery: reviews context
- Warning Features → Warning Evaluation: supplies features (evidence: `src/analysis/ew_eval.py`)
- Inspection Committee → What-if Scenarios: explores what-if (evidence: `README.md`)
- Inspection Committee → Inspection Context: uses contexts (evidence: `README.md`)
- Inspection Context → Guarded Reports: renders report (evidence: `src/inference/inspection_report.py`)
- Dashboard Chat User → Chat Interface: asks question (evidence: `README.md`)
- Chat Interface → Chat API: sends question
- Chat API → Answer Service: processes question (evidence: `chatbot/app/api/main.py`)
- Answer Service → Hybrid Retrieval: retrieves evidence (evidence: `chatbot/app/generation/service.py`)
- Hybrid Retrieval → Intent Router: routes query (evidence: `chatbot/app/retrieval/hybrid.py`)
- Hybrid Retrieval → Structured Facts: reads facts (evidence: `chatbot/app/retrieval/hybrid.py`)
- Hybrid Retrieval → Vector Search: searches documents (evidence: `chatbot/app/retrieval/hybrid.py`)
- Answer Service → Local Answer Builder: builds local answer (evidence: `chatbot/app/generation/service.py`)
- Answer Service → Gemini Generation: generates answer (evidence: `chatbot/app/generation/service.py`)
