# ishan1o1/logbox architecture

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

- Interactive diagram: https://gitdiagram.com/ishan1o1/logbox
- Repository: https://github.com/ishan1o1/logbox

## Overview

#### Purpose and Runtime Shape
This repository is a log-observability and incident root-cause-analysis (RCA) system. It combines a React/Vite frontend with a Node.js server that appears to query Elasticsearch-backed logs, present analytics dashboards, and generate RCA output through an AI-provider abstraction.

Key runtime entry points:
- Frontend bootstrap: `frontend/src/main.jsx`, application composition: `frontend/src/App.jsx`
- Backend HTTP process: `server/server.js`
- Containerized local environment: `docker-compose.yml`

#### Frontend Application Shell and Access Control
The frontend is a single-page application organized around dashboard, authentication, and RCA routes/pages. Authentication and theme state are shared through React contexts; protected route handling separates authenticated operational views from login/signup access.

Core paths:
- `frontend/src/context/AuthContext.jsx`
- `frontend/src/components/ProtectedRoute.jsx`
- `frontend/src/pages/Login.jsx`
- `frontend/src/pages/AdminDashboard.jsx`

#### Log Analytics Dashboard
The admin dashboard composes log-oriented operational views: tabular/list displays, filtering, duration selection, charts, error-rate summaries, and incident cards. These components form the primary analyst workflow for inspecting indexed events and recognizing incidents.

Core paths:
- `frontend/src/pages/AdminDashboard.jsx`
- `frontend/src/components/AnalyticsOverview.jsx`
- `frontend/src/components/LogTable.jsx`
- `frontend/src/components/LogFilters.jsx`
- `frontend/src/components/ErrorRateCards.jsx`

The likely UI data boundary is the service layer, which isolates HTTP/API calls from visualization components:
- `frontend/src/services/analyticsApi.js`
- `frontend/src/components/LogChart.jsx`

#### RCA Workflow
RCA is a distinct frontend-to-backend capability. The UI presents an RCA page and modal interaction, while the server module owns request routing, orchestration, prompt construction, and AI invocation. This separation allows analysis logic and provider selection to evolve without embedding AI details in the client.

Core paths:
- `frontend/src/pages/RCA.jsx`
- `frontend/src/components/RCAModal.jsx`
- `frontend/src/services/rcaApi.js`
- `server/modules/rca/rca.routes.js`
- `server/modules/rca/rca.controller.js`
- `server/modules/rca/rca.service.js`

Control flow: user selects or investigates an incident/log context → frontend RCA service submits analysis request → controller delegates to RCA service → service assembles/uses an AI analysis result → response is rendered in the RCA page/modal.

#### AI Provider Boundary
AI-specific behavior is modularized under the RCA module. Prompt definition and provider access are separated from RCA transport and business orchestration, creating a clear boundary for changing models or credentials.

Core paths:
- `server/modules/rca/rca.ai.service.js`
- `server/modules/rca/rca.prompt.js`
- `server/modules/rca/ai/provider.js`

`server/testGemini.js` indicates Gemini may be a supported or evaluated external AI service, but production provider configuration should be verified in the implementation.

#### Log Storage, Ingestion, and Elasticsearch
Elasticsearch is the apparent primary log datastore. The server includes connection configuration, a log model, index creation support, and buffering, suggesting logs may be accumulated before being written or processed in batches.

Core paths:
- `server/config/elasticsearch.js`
- `server/models/log.js`
- `server/services/logBuffer.js`
- `server/utils/createIndex.js`

Supporting artifacts such as `server/mapping.json`, `server/indices.json`, and `server/demo_logs.json` likely define index structure and sample/bootstrap data. Elasticsearch is the principal infrastructure dependency and the backend is the boundary between it and the browser.

#### Deployment and Dependency Boundaries
The repository has independently packaged frontend and server projects:
- `frontend/package.json`
- `server/package.json`

The frontend is Vite-based (`frontend/vite.config.js`), while the server owns Elasticsearch and AI-provider integrations. `docker-compose.yml` is the central infrastructure composition point and likely coordinates local service startup, including Elasticsearch and application runtime dependencies.

Main entry points: [`frontend/src/App.jsx`](https://github.com/ishan1o1/logbox/blob/main/frontend/src/App.jsx) (Application shell), [`server/server.js`](https://github.com/ishan1o1/logbox/blob/main/server/server.js) (HTTP server), [`frontend/src/components/ProtectedRoute.jsx`](https://github.com/ishan1o1/logbox/blob/main/frontend/src/components/ProtectedRoute.jsx) (Protected routes), [`server/modules/rca/rca.service.js`](https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.service.js) (RCA orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_frontend_bootstrap["Vite bootstrap<br/>frontend entry<br/>[main.jsx]"]
  node_app_shell["Application shell<br/>React composition<br/>[App.jsx]"]
  node_auth_context["Auth context<br/>React context<br/>[AuthContext.jsx]"]
  node_protected_route["Protected routes<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_login["Login<br/>auth page<br/>[Login.jsx]"]
  node_admin_dashboard["Admin dashboard<br/>analytics page<br/>[AdminDashboard.jsx]"]
  node_analytics_views["Analytics views<br/>dashboard components"]
  node_analytics_api["Analytics API client<br/>HTTP client<br/>[analyticsApi.js]"]
  node_rca_ui["RCA UI<br/>RCA page<br/>[RCA.jsx]"]
  node_rca_api["RCA API client<br/>HTTP client<br/>[rcaApi.js]"]
end

subgraph group_backend["Node.js backend"]
  node_server["HTTP server<br/>Node.js entry<br/>[server.js]"]
  node_rca_routes["RCA routes<br/>HTTP routes<br/>[rca.routes.js]"]
  node_rca_controller["RCA controller<br/>request controller<br/>[rca.controller.js]"]
  node_rca_service["RCA orchestration<br/>application service<br/>[rca.service.js]"]
  node_prompt["RCA prompt<br/>prompt definition<br/>[rca.prompt.js]"]
  node_ai_service["AI analysis service<br/>AI adapter<br/>[rca.ai.service.js]"]
  node_ai_provider["AI provider<br/>provider abstraction<br/>[provider.js]"]
  node_log_buffer["Log buffer<br/>ingestion buffer<br/>[logBuffer.js]"]
  node_log_model["Log model<br/>log persistence model<br/>[log.js]"]
  node_elasticsearch_config["Elasticsearch connection<br/>datastore client<br/>[elasticsearch.js]"]
end

subgraph group_infra["Infrastructure"]
  node_elasticsearch[("Elasticsearch<br/>log datastore")]
  node_compose["Local compose<br/>container composition<br/>[docker-compose.yml]"]
end

node_frontend_bootstrap -->|"mounts"| node_app_shell
node_app_shell -->|"uses"| node_auth_context
node_app_shell -->|"guards views with"| node_protected_route
node_protected_route -->|"redirects unauthenticated users to"| node_login
node_protected_route -->|"allows access to"| node_admin_dashboard
node_admin_dashboard -->|"composes"| node_analytics_views
node_analytics_views -->|"loads data through"| node_analytics_api
node_app_shell -->|"routes to"| node_rca_ui
node_rca_ui -->|"submits analysis through"| node_rca_api
node_analytics_api -->|"HTTP requests"| node_server
node_rca_api -->|"RCA request"| node_rca_routes
node_server -->|"mounts"| node_rca_routes
node_rca_routes -->|"dispatches to"| node_rca_controller
node_rca_controller -->|"delegates to"| node_rca_service
node_rca_service -->|"uses"| node_prompt
node_rca_service -->|"requests analysis from"| node_ai_service
node_ai_service -->|"invokes through"| node_ai_provider
node_server -->|"ingests logs via"| node_log_buffer
node_log_buffer -->|"batches for"| node_log_model
node_log_model -->|"uses client"| node_elasticsearch_config
node_elasticsearch_config -->|"connects to"| node_elasticsearch
node_compose -.->|"runs"| node_server
node_compose -.->|"provisions"| node_elasticsearch

click node_frontend_bootstrap "https://github.com/ishan1o1/logbox/blob/main/frontend/src/main.jsx"
click node_app_shell "https://github.com/ishan1o1/logbox/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/ishan1o1/logbox/blob/main/frontend/src/context/AuthContext.jsx"
click node_protected_route "https://github.com/ishan1o1/logbox/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_login "https://github.com/ishan1o1/logbox/blob/main/frontend/src/pages/Login.jsx"
click node_admin_dashboard "https://github.com/ishan1o1/logbox/blob/main/frontend/src/pages/AdminDashboard.jsx"
click node_analytics_views "https://github.com/ishan1o1/logbox/blob/main/frontend/src/components/AnalyticsOverview.jsx"
click node_analytics_api "https://github.com/ishan1o1/logbox/blob/main/frontend/src/services/analyticsApi.js"
click node_rca_ui "https://github.com/ishan1o1/logbox/blob/main/frontend/src/pages/RCA.jsx"
click node_rca_api "https://github.com/ishan1o1/logbox/blob/main/frontend/src/services/rcaApi.js"
click node_server "https://github.com/ishan1o1/logbox/blob/main/server/server.js"
click node_rca_routes "https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.routes.js"
click node_rca_controller "https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.controller.js"
click node_rca_service "https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.service.js"
click node_prompt "https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.prompt.js"
click node_ai_service "https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.ai.service.js"
click node_ai_provider "https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/ai/provider.js"
click node_log_buffer "https://github.com/ishan1o1/logbox/blob/main/server/services/logBuffer.js"
click node_log_model "https://github.com/ishan1o1/logbox/blob/main/server/models/log.js"
click node_elasticsearch_config "https://github.com/ishan1o1/logbox/blob/main/server/config/elasticsearch.js"
click node_compose "https://github.com/ishan1o1/logbox/blob/main/docker-compose.yml"

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_frontend_bootstrap,node_app_shell,node_auth_context,node_protected_route,node_login,node_admin_dashboard,node_analytics_views,node_analytics_api,node_rca_ui,node_rca_api toneBlue
class node_server,node_rca_routes,node_rca_controller,node_rca_service,node_prompt,node_ai_service,node_ai_provider,node_log_buffer,node_log_model,node_elasticsearch_config toneAmber
class node_elasticsearch,node_compose toneMint
```

## Components

### React frontend

Authenticated analyst interface and API clients.

- [Vite bootstrap](https://github.com/ishan1o1/logbox/blob/main/frontend/src/main.jsx): frontend entry · `frontend/src/main.jsx`
- [Application shell](https://github.com/ishan1o1/logbox/blob/main/frontend/src/App.jsx): React composition · `frontend/src/App.jsx`
- [Auth context](https://github.com/ishan1o1/logbox/blob/main/frontend/src/context/AuthContext.jsx): React context · Supplies shared authentication state. · `frontend/src/context/AuthContext.jsx`
- [Protected routes](https://github.com/ishan1o1/logbox/blob/main/frontend/src/components/ProtectedRoute.jsx): route guard · `frontend/src/components/ProtectedRoute.jsx`
- [Login](https://github.com/ishan1o1/logbox/blob/main/frontend/src/pages/Login.jsx): auth page · `frontend/src/pages/Login.jsx`
- [Admin dashboard](https://github.com/ishan1o1/logbox/blob/main/frontend/src/pages/AdminDashboard.jsx): analytics page · Primary log investigation workspace. · `frontend/src/pages/AdminDashboard.jsx`
- [Analytics views](https://github.com/ishan1o1/logbox/blob/main/frontend/src/components/AnalyticsOverview.jsx): dashboard components · Overview, log table, filters, charts, and error-rate cards. · `frontend/src/components/AnalyticsOverview.jsx`
- [Analytics API client](https://github.com/ishan1o1/logbox/blob/main/frontend/src/services/analyticsApi.js): HTTP client · `frontend/src/services/analyticsApi.js`
- [RCA UI](https://github.com/ishan1o1/logbox/blob/main/frontend/src/pages/RCA.jsx): RCA page · Presents RCA requests and results. · `frontend/src/pages/RCA.jsx`
- [RCA API client](https://github.com/ishan1o1/logbox/blob/main/frontend/src/services/rcaApi.js): HTTP client · `frontend/src/services/rcaApi.js`

### Node.js backend

HTTP boundary, log storage integration, and RCA orchestration.

- [HTTP server](https://github.com/ishan1o1/logbox/blob/main/server/server.js): Node.js entry · `server/server.js`
- [RCA routes](https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.routes.js): HTTP routes · `server/modules/rca/rca.routes.js`
- [RCA controller](https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.controller.js): request controller · `server/modules/rca/rca.controller.js`
- [RCA orchestration](https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.service.js): application service · Builds and coordinates root-cause analysis. · `server/modules/rca/rca.service.js`
- [RCA prompt](https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.prompt.js): prompt definition · `server/modules/rca/rca.prompt.js`
- [AI analysis service](https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/rca.ai.service.js): AI adapter · `server/modules/rca/rca.ai.service.js`
- [AI provider](https://github.com/ishan1o1/logbox/blob/main/server/modules/rca/ai/provider.js): provider abstraction · Encapsulates external model access. · `server/modules/rca/ai/provider.js`
- [Log buffer](https://github.com/ishan1o1/logbox/blob/main/server/services/logBuffer.js): ingestion buffer · Accumulates logs before batch processing or writes. · `server/services/logBuffer.js`
- [Log model](https://github.com/ishan1o1/logbox/blob/main/server/models/log.js): log persistence model · `server/models/log.js`
- [Elasticsearch connection](https://github.com/ishan1o1/logbox/blob/main/server/config/elasticsearch.js): datastore client · `server/config/elasticsearch.js`

### Infrastructure

Local composition and external service dependencies.

- **Elasticsearch**: log datastore · Primary indexed log store.
- [Local compose](https://github.com/ishan1o1/logbox/blob/main/docker-compose.yml): container composition · Coordinates local application infrastructure. · `docker-compose.yml`

## Connections

- Vite bootstrap → Application shell: mounts
- Application shell → Auth context: uses
- Application shell → Protected routes: guards views with
- Protected routes → Login: redirects unauthenticated users to
- Protected routes → Admin dashboard: allows access to
- Admin dashboard → Analytics views: composes
- Analytics views → Analytics API client: loads data through
- Application shell → RCA UI: routes to
- RCA UI → RCA API client: submits analysis through
- Analytics API client → HTTP server: HTTP requests
- RCA API client → RCA routes: RCA request
- HTTP server → RCA routes: mounts
- RCA routes → RCA controller: dispatches to
- RCA controller → RCA orchestration: delegates to
- RCA orchestration → RCA prompt: uses
- RCA orchestration → AI analysis service: requests analysis from
- AI analysis service → AI provider: invokes through
- HTTP server → Log buffer: ingests logs via
- Log buffer → Log model: batches for
- Log model → Elasticsearch connection: uses client
- Elasticsearch connection → Elasticsearch: connects to
- Local compose → HTTP server: runs
- Local compose → Elasticsearch: provisions