Skip to content

Commit 123c818

Browse files
update: README.md
1 parent 66d4e9c commit 123c818

1 file changed

Lines changed: 229 additions & 64 deletions

File tree

README.md

Lines changed: 229 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,193 @@
11
# SentraCore
22

3-
SentraCore is a **Local System Behavior Intelligence Platform** for Windows. It continuously analyzes system telemetry to understand performance behavior, detect statistical anomalies, explain the root cause of slowdowns, and forecast resource exhaustion before it occurs.
3+
SentraCore is a local system behavior intelligence platform for Windows that continuously analyzes system telemetry to understand performance behavior, detect statistical anomalies, explain performance degradation, and estimate future resource exhaustion before it impacts usability.
44

5-
Unlike traditional monitoring tools that display raw snapshots, SentraCore interprets system behavior over time — answering not just *what* is happening, but *why* it is happening and *when* it will become critical.
5+
Unlike traditional monitoring tools that focus on raw real-time snapshots, SentraCore interprets system behavior over time — helping users understand not only what is happening, but also why it is happening, how severe it is, and how it may affect system responsiveness.
6+
7+
---
8+
9+
## Overview
10+
11+
SentraCore combines:
12+
13+
- Real-time telemetry collection
14+
- Adaptive baseline learning
15+
- Statistical anomaly detection
16+
- Correlation-based root cause analysis
17+
- Predictive resource forecasting
18+
- Historical system behavior tracking
19+
- User-impact focused diagnostics
20+
21+
The platform is designed as a lightweight local intelligence layer running continuously in the background with minimal overhead.
622

723
---
824

925
## Current Status
1026

11-
**All six phases are complete and production-ready.**
27+
SentraCore is actively developed and currently includes a production-ready monitoring engine, behavioral intelligence system, predictive analysis pipeline, and Windows desktop dashboard.
1228

13-
| Phase | Name | Status |
14-
|---|---|---|
15-
| Phase 1 | Core Telemetry Engine | Complete |
16-
| Phase 2 | Behavioral Intelligence Layer | Complete |
17-
| Phase 3 | Correlation & Root Cause Engine | Complete |
18-
| Phase 4 | Prediction & Risk Engine | Complete |
19-
| Phase 5 | Flutter Dashboard System | Complete |
20-
| Phase 6 | Productization Layer | Complete |
29+
| Layer | Status |
30+
|---|---|
31+
| Core Telemetry Engine | Stable |
32+
| Behavioral Intelligence Layer | Stable |
33+
| Correlation & Root Cause Analysis | Stable |
34+
| Predictive Risk Engine | Stable |
35+
| Flutter Desktop Dashboard | Stable |
36+
| Windows Packaging & Installer | Stable |
2137

2238
---
2339

24-
## What SentraCore Does
40+
## Core Capabilities
2541

2642
### System Stability Index
27-
The primary dashboard metric is the **System Stability Index (1–100)**. Unlike a raw CPU percentage, this score synthesises instantaneous resource pressure, statistical anomaly deviation, and forward-looking predictive risk into a single, actionable number. A score of 100 is perfect health.
43+
44+
SentraCore generates a unified **System Stability Index (1–100)** representing overall system health.
45+
46+
The score combines:
47+
- Resource pressure
48+
- Behavioral deviation
49+
- Sustained stress trends
50+
- Predictive degradation risk
51+
52+
Rather than exposing isolated metrics, the Stability Index provides a high-level understanding of system condition and responsiveness.
53+
54+
---
55+
56+
### Behavioral Intelligence
57+
58+
The platform continuously models normal system behavior using adaptive baselines.
59+
60+
SentraCore learns:
61+
- Typical CPU activity
62+
- Memory consumption patterns
63+
- Disk activity behavior
64+
- Time-of-day workload trends
65+
66+
This allows the system to distinguish between expected workload spikes and abnormal behavior.
67+
68+
---
69+
70+
### Statistical Anomaly Detection
71+
72+
SentraCore uses statistical deviation analysis to identify abnormal system states.
73+
74+
Detection includes:
75+
- Sustained deviation from baseline
76+
- Resource volatility spikes
77+
- Abnormal trend acceleration
78+
- Multi-resource pressure correlation
79+
80+
Anomaly sensitivity can be configured by the user.
81+
82+
---
2883

2984
### Root Cause Analysis
30-
When the system enters a high-stress state and an alert fires, SentraCore's Correlation Engine automatically generates a **Root Cause Analysis** — identifying the primary bottleneck (CPU, Memory, or Disk), the most likely offending process, and the system event that triggered the degradation.
85+
86+
When degradation events occur, the Correlation Engine analyzes:
87+
88+
- Process activity
89+
- Resource contention
90+
- System event timing
91+
- Trend alignment
92+
93+
The engine then generates a ranked explanation of likely contributing factors.
94+
95+
Example:
96+
97+
- Elevated memory pressure from browser processes
98+
- Increased disk activity from indexing services
99+
- Sustained CPU saturation from background workloads
100+
101+
---
31102

32103
### Predictive Forecasting
33-
The Prediction Engine uses Exponential Moving Averages on trend slopes to generate **Time-to-Exhaustion (ETA)** countdowns. If memory is growing at a sustained rate, SentraCore will warn you that saturation is expected in X seconds, not just that usage is high.
34104

35-
### Adaptive Baseline Learning
36-
SentraCore does not use static thresholds. It learns what is *normal* for the specific machine it runs on, segmented by time-of-day. A CPU spike at 2 AM during a known backup job is treated differently from the same spike at 2 PM.
105+
SentraCore estimates future resource exhaustion using trend-based forecasting models.
106+
107+
Capabilities include:
108+
- Memory saturation estimation
109+
- CPU trend projection
110+
- Disk pressure forecasting
111+
- Time-to-exhaustion estimation (ETA)
112+
113+
This enables proactive alerts before severe degradation occurs.
37114

38115
---
39116

40-
## Architecture
117+
### Historical Monitoring (Logbook)
41118

42-
SentraCore is structured as two decoupled layers communicating over a local WebSocket and REST API:
119+
The dashboard automatically records and visualizes historical system behavior over time.
43120

44-
```
121+
Supported views include:
122+
- CPU pressure history
123+
- Memory pressure history
124+
- Disk pressure history
125+
- Interactive time filtering
126+
- Date-range analysis
127+
128+
History is stored locally on the machine.
129+
130+
---
131+
132+
### Process Intelligence
133+
134+
Processes are evaluated using sustained impact analysis rather than instantaneous usage alone.
135+
136+
Features include:
137+
- Process grouping by executable
138+
- Sustained resource contribution tracking
139+
- Ranked impact analysis
140+
- Process lifecycle cleanup for stale PIDs
141+
- Expandable per-process details
142+
143+
---
144+
145+
### Alerting & Diagnostics
146+
147+
SentraCore includes a real-time alerting and diagnostics system.
148+
149+
Features:
150+
- Alert history tracking
151+
- Root cause summaries
152+
- WebSocket-powered live alerts
153+
- Windows desktop notifications
154+
- Diagnostics timeline integration
155+
156+
---
157+
158+
### Safeguard System (Optional)
159+
160+
An optional safeguard layer can automatically terminate selected user-approved processes during severe degradation scenarios.
161+
162+
Features:
163+
- Live process selection
164+
- Flexible executable matching
165+
- User-controlled targeting
166+
- Logged termination outcomes
167+
- Safety-focused restrictions
168+
169+
---
170+
171+
## System Architecture
172+
173+
SentraCore is structured as two decoupled layers communicating over local APIs and WebSockets.
174+
175+
```text
45176
Flutter Dashboard (Windows Desktop)
46-
WebSocket (ws://localhost:8740/ws/live)
47-
↕ REST API (http://localhost:8740/api/v1/)
48-
Python Engine (Headless Background Process)
49-
├── SystemCollector (psutil telemetry)
50-
├── Normalizer (EMA smoothing)
51-
├── TimeSeriesBuffer (ring buffers)
52-
├── BaselineModel (adaptive learning)
53-
├── TrendAnalyzer (linear regression)
54-
├── AnomalyDetector (Z-score analysis)
55-
├── StressEngine (multi-state composite)
56-
├── PredictionEngine (ETA forecasting)
57-
├── StabilityCalculator (global health index)
58-
├── CorrelationEngine (root cause analysis)
59-
└── AlertManager (threshold evaluation)
177+
WebSocket / REST API
178+
Python Monitoring & Intelligence Engine
179+
├── SystemCollector
180+
├── SignalNormalizer
181+
├── TimeSeriesBuffer
182+
├── BaselineModel
183+
├── TrendAnalyzer
184+
├── AnomalyDetector
185+
├── StressEngine
186+
├── PredictionEngine
187+
├── StabilityCalculator
188+
├── CorrelationEngine
189+
├── AlertManager
190+
└── SafeguardController
60191
```
61192

62193
---
@@ -65,64 +196,98 @@ Python Engine (Headless Background Process)
65196

66197
| Layer | Technology |
67198
|---|---|
68-
| Monitoring Engine | Python 3.11, psutil |
69-
| API Server | FastAPI, uvicorn |
70-
| Real-time Communication | WebSockets |
71-
| Dashboard UI | Flutter (Dart), Windows Desktop |
72-
| Build & Packaging | PyInstaller, Inno Setup |
73-
| CI/CD | GitHub Actions (ruff, pytest, flutter analyze) |
199+
| Monitoring Engine | Python 3.11 |
200+
| Telemetry Collection | psutil |
201+
| API Server | FastAPI |
202+
| Real-Time Communication | WebSockets |
203+
| Dashboard UI | Flutter Desktop (Windows) |
204+
| Packaging | PyInstaller |
205+
| Installer | Inno Setup |
206+
| CI/CD | GitHub Actions |
74207
| Testing | pytest, flutter test |
75208

76209
---
77210

78-
## Getting Started
211+
## Installation
212+
213+
### Windows Installer
214+
215+
Download the latest installer from the [Releases](../../releases) page.
216+
217+
The installer:
218+
- Installs SentraCore into `C:\Program Files\SentraCore\`
219+
- Creates Desktop and Start Menu shortcuts
220+
- Optionally enables startup launch behavior
221+
- Configures the monitoring engine automatically
222+
223+
---
224+
225+
## Development Setup
79226

80-
### Run in Development
227+
See the setup documentation for complete local development instructions.
81228

82-
See [docs/setup/development_setup.md](docs/setup/development_setup.md) for the full guide.
229+
### Run the Engine
83230

84231
```powershell
85-
# 1. Start the Python Engine
86232
.venv\Scripts\python -m engine.main
233+
```
87234

88-
# 2. In a second terminal, run the Flutter Dashboard
235+
### Run the Dashboard
236+
237+
```powershell
89238
cd dashboard
90239
flutter run -d windows
91240
```
92241

93-
### Install from Installer
94-
95-
Download the latest `SentraCore_Setup.exe` from the [Releases](../../releases) page and run it. The installer will:
96-
- Place both executables in `C:\Program Files\SentraCore\`.
97-
- Optionally configure the engine to start automatically on Windows login.
98-
- Create Desktop and Start Menu shortcuts for the dashboard.
99-
100242
---
101243

102244
## Documentation
103245

104246
| Document | Description |
105247
|---|---|
106-
| [Development Setup](docs/setup/development_setup.md) | Full local development environment guide |
107-
| [Engine Setup](docs/setup/engine_setup.md) | Engine-specific installation reference |
108-
| [Dashboard Setup](docs/setup/dashboard_setup.md) | Flutter-specific setup reference |
109-
| [Intelligence Pipeline](docs/architecture/intelligence_layer.md) | Deep dive into all 10 processing stages |
110-
| [Building SentraCore](docs/architecture/building.md) | How to produce production executables and the installer |
248+
| Development Setup | Local development environment setup |
249+
| Engine Setup | Python engine configuration |
250+
| Dashboard Setup | Flutter dashboard setup |
251+
| Architecture Overview | Internal processing pipeline |
252+
| Build & Packaging | Production build and installer process |
111253

112254
---
113255

114-
## Project Philosophy
256+
## Design Philosophy
115257

116258
SentraCore is built around five principles:
117259

118-
1. **Observation** — Collect accurate, smoothed system telemetry.
119-
2. **Behavioral Modeling** — Understand what is normal for this machine.
120-
3. **Anomaly Detection** — Detect statistically significant deviations.
121-
4. **Correlation Analysis** — Explain *why* the system is degrading.
122-
5. **Prediction** — Forecast *when* critical thresholds will be breached.
260+
1. Observation
261+
Collect reliable and structured telemetry.
262+
263+
2. Behavioral Modeling
264+
Learn what is normal for the machine.
265+
266+
3. Anomaly Detection
267+
Detect statistically significant deviations.
268+
269+
4. Correlation Analysis
270+
Explain likely causes of degradation.
271+
272+
5. Predictive Awareness
273+
Estimate future instability before impact occurs.
274+
275+
---
276+
277+
## Product Positioning
278+
279+
SentraCore is not a traditional monitoring dashboard.
280+
281+
It is a local system behavior intelligence platform focused on:
282+
283+
- behavioral understanding
284+
- anomaly detection
285+
- predictive system analysis
286+
- explainable diagnostics
287+
- user-impact interpretation
123288

124289
---
125290

126291
## License
127292

128-
Apache License.
293+
Apache License 2.0

0 commit comments

Comments
 (0)