Skip to content

Commit f63e2f5

Browse files
AsieduDevelopmentHubAsieduDevelopmentHub
committed
docs: add architecture and development setup documentation
1 parent 2128478 commit f63e2f5

3 files changed

Lines changed: 330 additions & 30 deletions

File tree

‎docs/architecture/building.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Building SentraCore
2+
3+
This guide covers how to produce standalone, production-ready executables and compile the final Windows installer.
4+
5+
---
6+
7+
## Prerequisites
8+
9+
| Requirement | Verification Command |
10+
|---|---|
11+
| Python 3.11+ with virtual environment | `.venv\Scripts\python --version` |
12+
| PyInstaller (installed in venv) | `.venv\Scripts\pyinstaller --version` |
13+
| Flutter SDK (stable) | `flutter --version` |
14+
| Visual Studio with "Desktop development with C++" | `flutter doctor` |
15+
| Inno Setup 6 | Installed from [jrsoftware.org](https://jrsoftware.org/isinfo.php) |
16+
17+
---
18+
19+
## Step 1: Build the Python Engine
20+
21+
```powershell
22+
scripts\build_engine.bat
23+
```
24+
25+
This script activates the virtual environment, cleans previous artifacts, runs PyInstaller with the correct hidden imports for `uvicorn` and `fastapi`, and outputs `SentraCoreEngine.exe` to the `dist/` directory.
26+
27+
The engine is compiled with `--noconsole` so it runs as a fully invisible background process.
28+
29+
**Output:** `dist\SentraCoreEngine.exe`
30+
31+
---
32+
33+
## Step 2: Build the Flutter Dashboard
34+
35+
```powershell
36+
scripts\build_dashboard.bat
37+
```
38+
39+
This script navigates to the `dashboard/` directory and runs `flutter build windows --release`.
40+
41+
> Note: Flutter bundles the executable alongside several required DLL files and data directories. The entire `Release\` folder contents must be included in the installer.
42+
43+
**Output:** `dashboard\build\windows\x64\runner\Release\`
44+
45+
---
46+
47+
## Step 3: Compile the Installer
48+
49+
1. Open **Inno Setup Compiler**.
50+
2. Go to **File → Open** and select `installer\sentracore.iss`.
51+
3. Press **Ctrl+F9** to compile.
52+
53+
**Output:** `dist\SentraCore_Setup_v1.0.exe`
54+
55+
---
56+
57+
## What the Installer Does
58+
59+
| Action | Detail |
60+
|---|---|
61+
| Install location | `C:\Program Files\SentraCore\` |
62+
| Desktop shortcut | Optional, user-selectable during install |
63+
| Start Menu group | `SentraCore\` with shortcuts to Dashboard and Uninstaller |
64+
| Auto-start on login | Adds `SentraCoreEngine.exe` to `HKCU\...\Run` (optional) |
65+
| Post-install launch | Starts the engine in background, optionally opens the dashboard |
66+
| Uninstall | Kills the engine process and removes all files and registry keys |
67+
68+
---
69+
70+
## Releasing a New Version
71+
72+
1. Update `__version__` in `engine/__init__.py`.
73+
2. Update `AppVersion` and `OutputBaseFilename` in `installer/sentracore.iss`.
74+
3. Commit all changes.
75+
4. Create and push an annotated Git tag:
76+
```powershell
77+
git tag -a v1.1.0 -m "Release v1.1.0"
78+
git push origin main --tags
79+
```
80+
5. Run the three build steps above to produce the new installer.
81+
6. Create a GitHub Release from the tag and attach the new `SentraCore_Setup_v*.exe` as a release asset.

‎docs/architecture/intelligence_layer.md‎

Lines changed: 124 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,124 @@
1-
# Behavioral Intelligence Layer
2-
3-
SentraCore moves beyond static thresholds (e.g., "Alert if CPU > 90%") to implement context-aware, statistical analysis of system behavior.
4-
5-
## 1. Time-of-Day Segmenting
6-
System behavior changes throughout the day. A backup script running at 2 AM might spike the CPU to 100%, which is *normal* for that time, but a spike to 100% at 2 PM might be an anomaly.
7-
We break the day into 4 segments:
8-
- **Night:** 00:00 - 06:00
9-
- **Morning:** 06:00 - 12:00
10-
- **Afternoon:** 12:00 - 18:00
11-
- **Evening:** 18:00 - 24:00
12-
13-
The `BaselineModel` stores separate standard deviations and means for each segment.
14-
15-
## 2. Statistical Anomaly Detection (Z-Scores)
16-
The `AnomalyDetector` evaluates the current snapshot against the active Time-of-Day segment.
17-
- Instead of raw percentages, it calculates the Z-Score: `(Current - Mean) / Standard Deviation`.
18-
- Anomalies must be **sustained** over multiple cycles to trigger an elevated stress response, preventing micro-spikes from causing false alarms.
19-
20-
## 3. Trend Analysis
21-
The `TrendAnalyzer` performs linear regression over the short-term buffer (last 60 seconds).
22-
- **CPU Slope:** Detects run-away processes before they hit 100%.
23-
- **Memory Slope:** Acts as a real-time memory leak detector.
24-
- **Volatility:** Calculates short-term standard deviation to measure system instability.
25-
26-
## 4. Multi-State Stress Engine
27-
The final Stress Score (0-100) is a composite of:
28-
1. Raw instantaneous resource pressure.
29-
2. Trend modifiers (growing slopes add penalty points).
30-
3. Anomaly modifiers (sustained z-score deviations multiply the pressure).
1+
# Intelligence Pipeline
2+
3+
This document explains how SentraCore transforms raw system telemetry into actionable, explainable intelligence across its ten processing stages.
4+
5+
---
6+
7+
## Overview
8+
9+
Raw telemetry alone is insufficient for meaningful system monitoring. A CPU reading of 95% could be normal during a scheduled batch job, or it could indicate a runaway process. SentraCore resolves this ambiguity through a sequential intelligence pipeline that layers context, statistics, and forecasting on top of raw data.
10+
11+
```
12+
SystemCollector
13+
→ Normalizer (EMA smoothing, spike detection)
14+
→ TimeSeriesBuffer (ring buffers for historical context)
15+
→ BaselineModel (per-segment adaptive learning)
16+
→ TrendAnalyzer (linear regression, slope, volatility)
17+
→ AnomalyDetector (Z-score deviation from baseline)
18+
→ StressEngine (multi-state composite score)
19+
→ PredictionEngine (ETA forecasting, risk scoring)
20+
→ StabilityCalculator (global health index)
21+
→ CorrelationEngine (root cause analysis, triggered on alert)
22+
→ AlertManager (threshold evaluation, RCA attachment)
23+
```
24+
25+
---
26+
27+
## Stage 1: System Collection
28+
29+
**Module:** `engine/collector/system_collector.py`
30+
31+
The `SystemCollector` samples system telemetry at a configurable interval (default: 2 seconds) using `psutil`. Each sample is a `SystemSnapshot` containing CPU percent, memory usage, disk I/O rates, and a UNIX timestamp.
32+
33+
---
34+
35+
## Stage 2: Normalization
36+
37+
**Module:** `engine/normalization/normalizer.py`
38+
39+
The `Normalizer` applies an **Exponential Moving Average (EMA)** to each metric, reducing the impact of instantaneous spikes on downstream analysis. It also independently detects spikes by comparing raw values against the rolling average.
40+
41+
---
42+
43+
## Stage 3: Time-Series Buffering
44+
45+
**Module:** `engine/buffer/time_series_buffer.py`
46+
47+
Normalized snapshots are pushed into two ring buffers:
48+
- **Short-window buffer:** Last ~60 seconds, used for trend analysis.
49+
- **Long-window buffer:** Last ~30 minutes, used for baseline learning.
50+
51+
---
52+
53+
## Stage 4: Baseline Learning
54+
55+
**Module:** `engine/baseline/baseline_model.py`
56+
57+
The `BaselineModel` learns what is *normal* for the specific machine. It segments the day into four time-of-day windows (Night, Morning, Afternoon, Evening) and maintains a running mean and standard deviation per metric per segment. Static thresholds are never used.
58+
59+
---
60+
61+
## Stage 5: Trend Analysis
62+
63+
**Module:** `engine/intelligence/trend_analyzer.py`
64+
65+
The `TrendAnalyzer` performs **linear regression** over the short-window buffer to compute CPU and Memory slope (% change per second) and volatility (short-term standard deviation). A positive, sustained memory slope can indicate a memory leak.
66+
67+
---
68+
69+
## Stage 6: Anomaly Detection
70+
71+
**Module:** `engine/intelligence/anomaly_detector.py`
72+
73+
The `AnomalyDetector` calculates a Z-Score for each metric against the active time-of-day baseline:
74+
75+
```
76+
Z = (Current Value - Baseline Mean) / Baseline Standard Deviation
77+
```
78+
79+
Anomalies must be sustained over multiple consecutive cycles before being classified as elevated or severe, preventing transient micro-spikes from generating false alerts.
80+
81+
---
82+
83+
## Stage 7: Multi-State Stress Engine
84+
85+
**Module:** `engine/stress/stress_engine.py`
86+
87+
The `StressEngine` consolidates upstream analysis into a single **Stress Score (0–100)** weighted across three dimensions:
88+
1. Instantaneous resource pressure (CPU, Memory, Disk).
89+
2. Trend modifiers (growing slopes add a forward-looking penalty).
90+
3. Anomaly modifiers (sustained z-score deviations multiply the base pressure).
91+
92+
---
93+
94+
## Stage 8: Prediction & Risk Engine
95+
96+
**Module:** `engine/intelligence/prediction_engine.py`
97+
98+
The `PredictionEngine` uses EMA-smoothed trend slopes to forecast:
99+
- **Time-to-Exhaustion (ETA):** Seconds until Memory hits 98% or CPU hits 95%.
100+
- **Risk Score (0–100%):** Probabilistic assessment of severe degradation within the next 5 minutes.
101+
102+
---
103+
104+
## Stage 9: System Stability Index
105+
106+
**Module:** `engine/intelligence/stability_index.py`
107+
108+
The `StabilityCalculator` synthesises all upstream signals into a **System Stability Index (1–100)**. The index is a weighted composite of:
109+
- **50%** Instantaneous Stress Score
110+
- **30%** Predictive Risk Score
111+
- **20%** Anomaly Score
112+
113+
---
114+
115+
## Stage 10: Correlation & Root Cause Analysis
116+
117+
**Module:** `engine/intelligence/correlation_engine.py`
118+
119+
Invoked lazily only when an alert fires, the `CorrelationEngine` cross-references three data sources:
120+
1. **Bottleneck Identification:** Determines whether CPU, Memory, or Disk is the primary stressor.
121+
2. **Suspect Identification:** Cross-references against the `ProcessTracker` to find the top-impact process.
122+
3. **Trigger Identification:** Cross-references against the `EventLogger` to find the causal system event.
123+
124+
The resulting `RootCauseAnalysis` is attached to the `Alert` and broadcast via WebSocket to the dashboard.

‎docs/setup/development_setup.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Development Setup
2+
3+
This guide covers how to get the SentraCore development environment running on your local machine.
4+
5+
## Prerequisites
6+
7+
### Python Engine
8+
- Python 3.11 or higher
9+
- Git
10+
- Windows OS (some `psutil` telemetry counters are Windows-specific)
11+
12+
### Flutter Dashboard
13+
- Flutter SDK (stable channel, 3.x or higher)
14+
- Visual Studio 2022 Community or higher
15+
- **Required Workload:** Desktop development with C++
16+
- **Required Components:** MSVC v142 build tools, C++ CMake tools for Windows, Windows 10/11 SDK
17+
- Windows Developer Mode enabled
18+
19+
---
20+
21+
## Repository Structure
22+
23+
```
24+
SentraCore/
25+
├── engine/ # Python monitoring engine
26+
│ ├── alerts/ # Alert Manager and RCA integration
27+
│ ├── api/ # FastAPI REST and WebSocket server
28+
│ ├── baseline/ # Adaptive baseline model
29+
│ ├── buffer/ # Time-series ring buffers
30+
│ ├── collector/ # psutil system telemetry collector
31+
│ ├── events/ # System event logger
32+
│ ├── intelligence/ # Trend, Anomaly, Prediction, Stability engines
33+
│ ├── normalization/ # EMA-based metric normalizer
34+
│ ├── process/ # Process impact tracker
35+
│ └── stress/ # Multi-state stress engine
36+
├── dashboard/ # Flutter Windows desktop UI
37+
├── tests/ # Python unit tests
38+
├── docs/ # Project documentation
39+
├── scripts/ # Build automation scripts
40+
└── installer/ # Inno Setup installer configuration
41+
```
42+
43+
---
44+
45+
## Engine Setup
46+
47+
### 1. Create and Activate a Virtual Environment
48+
49+
```powershell
50+
python -m venv .venv
51+
.venv\Scripts\Activate
52+
```
53+
54+
### 2. Install Dependencies
55+
56+
```powershell
57+
pip install -r requirements.txt
58+
```
59+
60+
### 3. Run the Engine
61+
62+
The engine must be started as a module from the repository root so that all internal imports resolve correctly:
63+
64+
```powershell
65+
.venv\Scripts\python -m engine.main
66+
```
67+
68+
The engine will start and expose:
69+
- **REST API:** `http://localhost:8000/api/v1/`
70+
- **WebSocket (live state):** `ws://localhost:8000/ws/live`
71+
72+
### 4. Run the Test Suite
73+
74+
```powershell
75+
.venv\Scripts\python -m pytest tests/ -v
76+
```
77+
78+
### 5. Run the Linter
79+
80+
SentraCore uses `ruff` for static analysis. Run it before submitting any pull request:
81+
82+
```powershell
83+
.venv\Scripts\ruff check engine/ tests/ --select=E9,F63,F7,F82
84+
```
85+
86+
---
87+
88+
## Dashboard Setup
89+
90+
### 1. Enable Windows Developer Mode
91+
92+
Flutter requires Windows Developer Mode to create necessary symlinks during the build.
93+
1. Open **Windows Settings**.
94+
2. Search for **Developer Mode**.
95+
3. Toggle it to **On**.
96+
97+
### 2. Install Flutter Dependencies
98+
99+
```powershell
100+
cd dashboard
101+
flutter pub get
102+
```
103+
104+
### 3. Run the Dashboard in Debug Mode
105+
106+
Ensure the Python Engine is running first, then:
107+
108+
```powershell
109+
flutter run -d windows
110+
```
111+
112+
### 4. Verify with Flutter Analyze
113+
114+
```powershell
115+
flutter analyze
116+
flutter test
117+
```
118+
119+
---
120+
121+
## Development Tips
122+
123+
- Always start the Python Engine before launching the Flutter Dashboard.
124+
- The engine's collection interval is configurable in `engine/config.py` via `COLLECTION_INTERVAL_SEC`.
125+
- Alert thresholds (`ALERT_STRESS_THRESHOLD`, `ALERT_CONSECUTIVE_COUNT`, `ALERT_COOLDOWN_SEC`) are also in `engine/config.py`.

0 commit comments

Comments
 (0)