# ningzestudio/logshare architecture

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

- Interactive diagram: https://gitdiagram.com/ningzestudio/logshare
- Repository: https://github.com/ningzestudio/logshare

## Overview

LogShare is a game-server log sharing and intelligent diagnosis platform. Its primary flow accepts and filters uploaded logs, stores them behind shareable IDs, and handles asynchronous deobfuscation and security review; users can then request AI diagnosis streamed over SSE. The diagnosis agent can use log-focused tools, web search, GitHub and local RAG, with trace and quality governance exposed to administrators. Edges are limited to relationships stated in the README or visible in indexed excerpts; unsampled controller and queue details are not inferred.

Main entry points: [`app/Agent/LogAgent.php`](https://github.com/ningzestudio/logshare/blob/main/app/Agent/LogAgent.php) (LogAgent engine), [`app/Log.php`](https://github.com/ningzestudio/logshare/blob/main/app/Log.php) (Log service), [`app/Rag/RagSearch.php`](https://github.com/ningzestudio/logshare/blob/main/app/Rag/RagSearch.php) (RAG retrieval), [`app/Controller/LogController.php`](https://github.com/ningzestudio/logshare/blob/main/app/Controller/LogController.php) (Log upload API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Upload and sharing"]
  node_upload["Log upload API<br/>[LogController.php]"]
  node_filters["Redaction filters"]
  node_log["Log service<br/>[Log.php]"]
  node_metadata["Log metadata<br/>[MetadataEntry.php]"]
  node_token["Delete token<br/>[Token.php]"]
  node_storage[("Storage backends")]
  node_raw["Log retrieval API<br/>[RawController.php]"]
end

subgraph group_async["Async processing"]
  node_eventqueue["Event queue<br/>[EventQueue.php]"]
  node_consumers["Queue consumers"]
  node_eventhandlers["Event handlers"]
end

subgraph group_diagnosis["AI diagnosis"]
  node_analysisapi["AI analysis API<br/>[AIController.php]"]
  node_analysisqueue["Analysis queue<br/>[AnalysisQueue.php]"]
  node_agent["LogAgent engine<br/>[LogAgent.php]"]
  node_agenttools["Agent tools"]
  node_ai["AI client<br/>[AIClient.php]"]
  node_sse["SSE streaming"]
  node_analysisrecords[("Trace records")]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_ragapi["RAG API<br/>[RagController.php]"]
  node_ragmanager["RAG management<br/>[RagManager.php]"]
  node_ragsearch["RAG retrieval<br/>[RagSearch.php]"]
  node_retrievalmetrics["Retrieval metrics"]
end

subgraph group_platform["Platform services"]
  node_redis[("Redis client<br/>[RedisClient.php]")]
  node_cache[("Redis cache<br/>[RedisCache.php]")]
  node_config["Configuration<br/>[Config.php]"]
  node_security["Security service"]
  node_metrics["AI metrics"]
  node_syslog["System logging<br/>[Syslog.php]"]
end

node_user(("API client"))

node_user -->|"uploads logs"| node_upload
node_upload -->|"redacts files"| node_filters
node_upload -->|"stores logs"| node_log
node_log -->|"reads and writes"| node_storage
node_log -->|"uses metadata"| node_metadata
node_log -->|"uses tokens"| node_token
node_user -->|"requests logs"| node_raw
node_log -->|"enqueues events"| node_eventqueue
node_consumers -->|"consumes events"| node_eventqueue
node_consumers -->|"dispatches events"| node_eventhandlers
node_user -->|"requests diagnosis"| node_analysisapi
node_analysisapi -->|"submits analysis"| node_analysisqueue
node_analysisqueue -->|"runs analysis"| node_agent
node_agent -->|"dispatches tools"| node_agenttools
node_agent -->|"queries model"| node_ai
node_agent -->|"retrieves context"| node_ragsearch
node_agent -->|"streams results"| node_sse
node_agent -->|"archives traces"| node_analysisrecords
node_user -->|"queries knowledge"| node_ragapi
node_ragapi -->|"searches index"| node_ragsearch
node_ragmanager -->|"builds index"| node_ragsearch
node_ragsearch -->|"records metrics"| node_retrievalmetrics
node_cache -->|"uses connection"| node_redis
node_analysisrecords -->|"stores records"| node_redis
node_config -->|"loads service"| node_security
node_metrics -->|"tracks jobs"| node_analysisqueue
node_syslog -->|"writes recent logs"| node_redis

click node_upload "https://github.com/ningzestudio/logshare/blob/main/app/Controller/LogController.php"
click node_filters "https://github.com/ningzestudio/logshare/tree/main/app/Filter"
click node_log "https://github.com/ningzestudio/logshare/blob/main/app/Log.php"
click node_metadata "https://github.com/ningzestudio/logshare/blob/main/app/Data/MetadataEntry.php"
click node_token "https://github.com/ningzestudio/logshare/blob/main/app/Data/Token.php"
click node_storage "https://github.com/ningzestudio/logshare/tree/main/app/Storage"
click node_raw "https://github.com/ningzestudio/logshare/blob/main/app/Controller/RawController.php"
click node_eventqueue "https://github.com/ningzestudio/logshare/blob/main/app/Queue/EventQueue.php"
click node_consumers "https://github.com/ningzestudio/logshare/blob/main/app/Process/EventQueueConsumer.php"
click node_eventhandlers "https://github.com/ningzestudio/logshare/tree/main/app/Queue/Handler"
click node_analysisapi "https://github.com/ningzestudio/logshare/blob/main/app/Controller/AIController.php"
click node_analysisqueue "https://github.com/ningzestudio/logshare/blob/main/app/Ai/AnalysisQueue.php"
click node_agent "https://github.com/ningzestudio/logshare/blob/main/app/Agent/LogAgent.php"
click node_agenttools "https://github.com/ningzestudio/logshare/tree/main/app/Agent/Tool"
click node_ai "https://github.com/ningzestudio/logshare/blob/main/app/Client/AIClient.php"
click node_sse "https://github.com/ningzestudio/logshare/tree/main/app/Sse"
click node_analysisrecords "https://github.com/ningzestudio/logshare/blob/main/app/Agent/AnalysisRecordManager.php"
click node_ragapi "https://github.com/ningzestudio/logshare/blob/main/app/Controller/RagController.php"
click node_ragmanager "https://github.com/ningzestudio/logshare/blob/main/app/Rag/RagManager.php"
click node_ragsearch "https://github.com/ningzestudio/logshare/blob/main/app/Rag/RagSearch.php"
click node_retrievalmetrics "https://github.com/ningzestudio/logshare/blob/main/app/Rag/RetrievalMetrics.php"
click node_redis "https://github.com/ningzestudio/logshare/blob/main/app/Client/RedisClient.php"
click node_cache "https://github.com/ningzestudio/logshare/blob/main/app/Cache/RedisCache.php"
click node_config "https://github.com/ningzestudio/logshare/blob/main/app/Config.php"
click node_security "https://github.com/ningzestudio/logshare/blob/main/app/System/SecurityService.php"
click node_metrics "https://github.com/ningzestudio/logshare/blob/main/app/System/AiMetricsService.php"
click node_syslog "https://github.com/ningzestudio/logshare/blob/main/app/Syslog.php"

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_upload,node_filters,node_log,node_metadata,node_token,node_storage,node_raw,node_user toneBlue
class node_eventqueue,node_consumers,node_eventhandlers toneAmber
class node_analysisapi,node_analysisqueue,node_agent,node_agenttools,node_ai,node_sse,node_analysisrecords toneMint
class node_ragapi,node_ragmanager,node_ragsearch,node_retrievalmetrics toneRose
class node_redis,node_cache,node_config,node_security,node_metrics,node_syslog toneIndigo
```

## Components

### Upload and sharing

- [Log upload API](https://github.com/ningzestudio/logshare/blob/main/app/Controller/LogController.php): `app/Controller/LogController.php`
- [Redaction filters](https://github.com/ningzestudio/logshare/tree/main/app/Filter): `app/Filter`
- [Log service](https://github.com/ningzestudio/logshare/blob/main/app/Log.php): `app/Log.php`
- [Log metadata](https://github.com/ningzestudio/logshare/blob/main/app/Data/MetadataEntry.php): `app/Data/MetadataEntry.php`
- [Delete token](https://github.com/ningzestudio/logshare/blob/main/app/Data/Token.php): `app/Data/Token.php`
- [Storage backends](https://github.com/ningzestudio/logshare/tree/main/app/Storage): `app/Storage`
- [Log retrieval API](https://github.com/ningzestudio/logshare/blob/main/app/Controller/RawController.php): `app/Controller/RawController.php`

### Async processing

- [Event queue](https://github.com/ningzestudio/logshare/blob/main/app/Queue/EventQueue.php): `app/Queue/EventQueue.php`
- [Queue consumers](https://github.com/ningzestudio/logshare/blob/main/app/Process/EventQueueConsumer.php): `app/Process/EventQueueConsumer.php`
- [Event handlers](https://github.com/ningzestudio/logshare/tree/main/app/Queue/Handler): `app/Queue/Handler`

### AI diagnosis

- [AI analysis API](https://github.com/ningzestudio/logshare/blob/main/app/Controller/AIController.php): `app/Controller/AIController.php`
- [Analysis queue](https://github.com/ningzestudio/logshare/blob/main/app/Ai/AnalysisQueue.php): `app/Ai/AnalysisQueue.php`
- [LogAgent engine](https://github.com/ningzestudio/logshare/blob/main/app/Agent/LogAgent.php): `app/Agent/LogAgent.php`
- [Agent tools](https://github.com/ningzestudio/logshare/tree/main/app/Agent/Tool): `app/Agent/Tool`
- [AI client](https://github.com/ningzestudio/logshare/blob/main/app/Client/AIClient.php): `app/Client/AIClient.php`
- [SSE streaming](https://github.com/ningzestudio/logshare/tree/main/app/Sse): `app/Sse`
- [Trace records](https://github.com/ningzestudio/logshare/blob/main/app/Agent/AnalysisRecordManager.php): `app/Agent/AnalysisRecordManager.php`

### Knowledge retrieval

- [RAG API](https://github.com/ningzestudio/logshare/blob/main/app/Controller/RagController.php): `app/Controller/RagController.php`
- [RAG management](https://github.com/ningzestudio/logshare/blob/main/app/Rag/RagManager.php): `app/Rag/RagManager.php`
- [RAG retrieval](https://github.com/ningzestudio/logshare/blob/main/app/Rag/RagSearch.php): `app/Rag/RagSearch.php`
- [Retrieval metrics](https://github.com/ningzestudio/logshare/blob/main/app/Rag/RetrievalMetrics.php): `app/Rag/RetrievalMetrics.php`

### Platform services

- [Redis client](https://github.com/ningzestudio/logshare/blob/main/app/Client/RedisClient.php): `app/Client/RedisClient.php`
- [Redis cache](https://github.com/ningzestudio/logshare/blob/main/app/Cache/RedisCache.php): `app/Cache/RedisCache.php`
- [Configuration](https://github.com/ningzestudio/logshare/blob/main/app/Config.php): `app/Config.php`
- [Security service](https://github.com/ningzestudio/logshare/blob/main/app/System/SecurityService.php): `app/System/SecurityService.php`
- [AI metrics](https://github.com/ningzestudio/logshare/blob/main/app/System/AiMetricsService.php): `app/System/AiMetricsService.php`
- [System logging](https://github.com/ningzestudio/logshare/blob/main/app/Syslog.php): `app/Syslog.php`

### Other components

- **API client**

## Connections

- API client → Log upload API: uploads logs (evidence: `README.md`)
- Log upload API → Redaction filters: redacts files (evidence: `README.md`)
- Log upload API → Log service: stores logs (evidence: `README.md`)
- Log service → Storage backends: reads and writes (evidence: `app/Log.php`)
- Log service → Log metadata: uses metadata (evidence: `app/Log.php`)
- Log service → Delete token: uses tokens (evidence: `app/Log.php`)
- API client → Log retrieval API: requests logs (evidence: `README.md`)
- Log service → Event queue: enqueues events (evidence: `README.md`)
- Queue consumers → Event queue: consumes events (evidence: `README.md`)
- Queue consumers → Event handlers: dispatches events (evidence: `README.md`)
- API client → AI analysis API: requests diagnosis (evidence: `README.md`)
- AI analysis API → Analysis queue: submits analysis
- Analysis queue → LogAgent engine: runs analysis (evidence: `app/Ai/AnalysisQueue.php`)
- LogAgent engine → Agent tools: dispatches tools (evidence: `README.md`)
- LogAgent engine → AI client: queries model (evidence: `README.md`)
- LogAgent engine → RAG retrieval: retrieves context (evidence: `README.md`)
- LogAgent engine → SSE streaming: streams results (evidence: `README.md`)
- LogAgent engine → Trace records: archives traces (evidence: `README.md`)
- API client → RAG API: queries knowledge (evidence: `README.md`)
- RAG API → RAG retrieval: searches index (evidence: `app/Controller/RagController.php`)
- RAG management → RAG retrieval: builds index (evidence: `app/Rag/RagManager.php`)
- RAG retrieval → Retrieval metrics: records metrics (evidence: `app/Rag/RagSearch.php`)
- Redis cache → Redis client: uses connection (evidence: `app/Cache/RedisCache.php`)
- Trace records → Redis client: stores records (evidence: `app/Agent/AnalysisRecordManager.php`)
- Configuration → Security service: loads service (evidence: `app/Config.php`)
- AI metrics → Analysis queue: tracks jobs (evidence: `app/System/AiMetricsService.php`)
- System logging → Redis client: writes recent logs (evidence: `app/Syslog.php`)
