# lightning-president-9/coc-ancient-ruins-website architecture

> Architecture diagram of the GitHub repository lightning-president-9/coc-ancient-ruins-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lightning-president-9/coc-ancient-ruins-website
- Repository: https://github.com/lightning-president-9/coc-ancient-ruins-website

## Overview

This is a Flask-based clan analytics and engagement website. Members use its web/API routes to explore current and former member records, monthly and longitudinal performance, forecasts, clusters, player reports, and dashboards; the KARSB chatbot turns natural-language questions into dataset-backed answers. The graph and chatbot flows are directly supported by excerpts; several README-listed capabilities have unsampled implementations, so their internal links are omitted rather than inferred.

Main entry points: [`chatbot/chat_controller.py`](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/chat_controller.py) (Chat Orchestrator), [`services/graph_service.py`](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/services/graph_service.py) (Graph Services), [`app.py`](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/app.py) (Flask App), [`routes/api_routes.py`](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/api_routes.py) (Member APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web and APIs"]
  node_flask["Flask App<br/>[app.py]"]
  node_api["Member APIs<br/>[api_routes.py]"]
  node_github_routes["GitHub Data APIs"]
  node_coc_routes["Game Data Pages<br/>[coc_routes.py]"]
  node_rate_limit["Rate Limiter<br/>[limiter_config.py]"]
end

subgraph group_data["Clan Data"]
  node_local_data[("Persisted Member Data<br/>[data_persist.py]")]
  node_remote_json[("Monthly Clan JSON")]
  node_github_service["GitHub Fetcher<br/>[github_service.py]"]
end

subgraph group_analytics["Analytics"]
  node_graph_routes["Graph Routes<br/>[graph_routes.py]"]
  node_graph_service["Graph Services<br/>[graph_service.py]"]
  node_member_graphs["Member Graphs"]
  node_former_graphs["Former Graphs"]
  node_monthly_graphs["Monthly Analysis"]
  node_all_month_graphs["Long-term Trends<br/>[all_month_graph.py]"]
  node_cluster_graphs["Member Clusters"]
  node_ai_routes["AI Routes<br/>[ai_routes.py]"]
  node_ai_service["Forecast Service<br/>[ai_service.py]"]
  node_prediction_graph["AI Predictions"]
end

subgraph group_engagement["Member Experiences"]
  node_player_dashboard["Player Dashboard"]
  node_player_data["Dashboard Data<br/>[player_data.py]"]
  node_player_report["Player Reports<br/>[player_report.py]"]
end

subgraph group_chat["KARSB Chatbot"]
  node_chat_routes["Chat Routes<br/>[chatbot_routes.py]"]
  node_chat_controller["Chat Orchestrator<br/>[chat_controller.py]"]
  node_month_normalizer["Month Parsing"]
  node_domain_router["Dataset Routing<br/>[domain_router.py]"]
  node_raw_fetcher["Data Fetching<br/>[raw_fetcher.py]"]
  node_operation_resolver["Operation Resolver"]
  node_response_builder["Response Builder"]
end

node_visitor(("Clan Member"))

node_visitor -->|"uses"| node_flask
node_flask -->|"registers routes"| node_api
node_flask -->|"registers routes"| node_github_routes
node_visitor -->|"requests datasets"| node_github_routes
node_github_routes -->|"fetches JSON"| node_github_service
node_github_service -->|"reads"| node_remote_json
node_api -.->|"serves records"| node_local_data
node_api -->|"applies limits"| node_rate_limit
node_visitor -->|"selects analyses"| node_graph_routes
node_graph_routes -->|"gets graph services"| node_graph_service
node_graph_service -->|"creates instance"| node_member_graphs
node_graph_service -->|"creates instance"| node_former_graphs
node_graph_service -->|"creates instance"| node_monthly_graphs
node_graph_service -->|"creates instance"| node_all_month_graphs
node_graph_service -->|"creates instance"| node_cluster_graphs
node_visitor -->|"views forecasts"| node_ai_routes
node_ai_routes -->|"requests forecast"| node_ai_service
node_ai_routes -->|"gets cluster service"| node_graph_service
node_visitor -->|"views dashboard"| node_player_dashboard
node_player_dashboard -.->|"loads player data"| node_player_data
node_visitor -->|"views reports"| node_player_report
node_visitor -->|"asks questions"| node_chat_routes
node_chat_routes -->|"dispatches message"| node_chat_controller
node_chat_controller -->|"normalizes month"| node_month_normalizer
node_chat_controller -->|"selects dataset"| node_domain_router
node_chat_controller -->|"fetches data"| node_raw_fetcher
node_chat_controller -->|"resolves operation"| node_operation_resolver
node_chat_controller -->|"builds answer"| node_response_builder
node_chat_controller -->|"uses hosted JSON"| node_remote_json
node_coc_routes -.->|"renders game pages"| node_visitor

click node_flask "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/app.py"
click node_api "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/api_routes.py"
click node_github_routes "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/github_api_routes.py"
click node_coc_routes "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/coc_routes.py"
click node_rate_limit "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/limiter_config.py"
click node_local_data "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/data_persist.py"
click node_github_service "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/services/github_service.py"
click node_graph_routes "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/graph_routes.py"
click node_graph_service "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/services/graph_service.py"
click node_member_graphs "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/clan_member_graph.py"
click node_former_graphs "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/former_member_graph.py"
click node_monthly_graphs "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/monthly_analysis_graph.py"
click node_all_month_graphs "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/all_month_graph.py"
click node_cluster_graphs "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/member_cluster_graph.py"
click node_ai_routes "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/ai_routes.py"
click node_ai_service "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/services/ai_service.py"
click node_prediction_graph "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/ai_prediction_graph.py"
click node_player_dashboard "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/dashboard/player_dashboard.py"
click node_player_data "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/dashboard/player_data.py"
click node_player_report "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/player_report.py"
click node_chat_routes "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/chatbot_routes.py"
click node_chat_controller "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/chat_controller.py"
click node_month_normalizer "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/month_normalizer.py"
click node_domain_router "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/domain_router.py"
click node_raw_fetcher "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/raw_fetcher.py"
click node_operation_resolver "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/operation_resolver.py"
click node_response_builder "https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/response_builder.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_flask,node_api,node_github_routes,node_coc_routes,node_rate_limit toneBlue
class node_local_data,node_remote_json,node_github_service toneAmber
class node_graph_routes,node_graph_service,node_member_graphs,node_former_graphs,node_monthly_graphs,node_all_month_graphs,node_cluster_graphs,node_ai_routes,node_ai_service,node_prediction_graph toneMint
class node_player_dashboard,node_player_data,node_player_report toneRose
class node_chat_routes,node_chat_controller,node_month_normalizer,node_domain_router,node_raw_fetcher,node_operation_resolver,node_response_builder,node_visitor toneIndigo
```

## Components

### Web and APIs

- [Flask App](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/app.py): `app.py`
- [Member APIs](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/api_routes.py): `routes/api_routes.py`
- [GitHub Data APIs](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/github_api_routes.py): `routes/github_api_routes.py`
- [Game Data Pages](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/coc_routes.py): `routes/coc_routes.py`
- [Rate Limiter](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/limiter_config.py): `limiter_config.py`

### Clan Data

- [Persisted Member Data](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/data_persist.py): `data_persist.py`
- **Monthly Clan JSON**
- [GitHub Fetcher](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/services/github_service.py): `services/github_service.py`

### Analytics

- [Graph Routes](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/graph_routes.py): `routes/graph_routes.py`
- [Graph Services](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/services/graph_service.py): `services/graph_service.py`
- [Member Graphs](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/clan_member_graph.py): `graphs/clan_member_graph.py`
- [Former Graphs](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/former_member_graph.py): `graphs/former_member_graph.py`
- [Monthly Analysis](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/monthly_analysis_graph.py): `graphs/monthly_analysis_graph.py`
- [Long-term Trends](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/all_month_graph.py): `graphs/all_month_graph.py`
- [Member Clusters](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/member_cluster_graph.py): `graphs/member_cluster_graph.py`
- [AI Routes](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/ai_routes.py): `routes/ai_routes.py`
- [Forecast Service](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/services/ai_service.py): `services/ai_service.py`
- [AI Predictions](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/ai_prediction_graph.py): `graphs/ai_prediction_graph.py`

### Member Experiences

- [Player Dashboard](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/dashboard/player_dashboard.py): `dashboard/player_dashboard.py`
- [Dashboard Data](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/dashboard/player_data.py): `dashboard/player_data.py`
- [Player Reports](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/graphs/player_report.py): `graphs/player_report.py`

### KARSB Chatbot

- [Chat Routes](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/routes/chatbot_routes.py): `routes/chatbot_routes.py`
- [Chat Orchestrator](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/chat_controller.py): `chatbot/chat_controller.py`
- [Month Parsing](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/month_normalizer.py): `chatbot/month_normalizer.py`
- [Dataset Routing](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/domain_router.py): `chatbot/domain_router.py`
- [Data Fetching](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/raw_fetcher.py): `chatbot/raw_fetcher.py`
- [Operation Resolver](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/operation_resolver.py): `chatbot/operation_resolver.py`
- [Response Builder](https://github.com/lightning-president-9/coc-ancient-ruins-website/blob/main/chatbot/response_builder.py): `chatbot/response_builder.py`

### Other components

- **Clan Member**

## Connections

- Clan Member → Flask App: uses
- Flask App → Member APIs: registers routes (evidence: `app.py`)
- Flask App → GitHub Data APIs: registers routes
- Clan Member → GitHub Data APIs: requests datasets
- GitHub Data APIs → GitHub Fetcher: fetches JSON (evidence: `routes/github_api_routes.py`)
- GitHub Fetcher → Monthly Clan JSON: reads (evidence: `services/github_service.py`)
- Member APIs → Persisted Member Data: serves records
- Member APIs → Rate Limiter: applies limits (evidence: `routes/api_routes.py`)
- Clan Member → Graph Routes: selects analyses
- Graph Routes → Graph Services: gets graph services (evidence: `routes/graph_routes.py`)
- Graph Services → Member Graphs: creates instance (evidence: `services/graph_service.py`)
- Graph Services → Former Graphs: creates instance (evidence: `services/graph_service.py`)
- Graph Services → Monthly Analysis: creates instance (evidence: `services/graph_service.py`)
- Graph Services → Long-term Trends: creates instance (evidence: `services/graph_service.py`)
- Graph Services → Member Clusters: creates instance (evidence: `services/graph_service.py`)
- Clan Member → AI Routes: views forecasts
- AI Routes → Forecast Service: requests forecast (evidence: `routes/ai_routes.py`)
- AI Routes → Graph Services: gets cluster service (evidence: `routes/ai_routes.py`)
- Clan Member → Player Dashboard: views dashboard
- Player Dashboard → Dashboard Data: loads player data
- Clan Member → Player Reports: views reports
- Clan Member → Chat Routes: asks questions
- Chat Routes → Chat Orchestrator: dispatches message (evidence: `routes/chatbot_routes.py`)
- Chat Orchestrator → Month Parsing: normalizes month (evidence: `chatbot/chat_controller.py`)
- Chat Orchestrator → Dataset Routing: selects dataset (evidence: `chatbot/chat_controller.py`)
- Chat Orchestrator → Data Fetching: fetches data (evidence: `chatbot/chat_controller.py`)
- Chat Orchestrator → Operation Resolver: resolves operation (evidence: `chatbot/chat_controller.py`)
- Chat Orchestrator → Response Builder: builds answer (evidence: `chatbot/chat_controller.py`)
- Chat Orchestrator → Monthly Clan JSON: uses hosted JSON
- Game Data Pages → Clan Member: renders game pages