⚡ SysNexus

An architecture intelligence tool that runs entirely in your browser.

---

What is this?

SysNexus is a tool that scans your codebase and gives you an interactive visual report of how everything connects dependencies, coupling, chokepoints, dead code, security risks, the whole picture.

You point it at a project folder (or a GitHub URL), wait a few seconds, and get back a self-contained HTML report with a force-directed graph, findings, and a workflow view. No installs beyond npm, no servers, no accounts. Everything happens in your browser tab.

UI Interface

Node Network

Dashboard

Findings

Workflow

---

Getting Started

git clone https://github.com/mic-tran/SysNexus.git
cd SysNexus
npm install
npm run build
npm run serve

Open http://localhost:3000 in Chrome or Edge, and then:

• 📂 Local Folder — pick a project directory from your machine (everything stays local)
• 🐙 GitHub Repo — paste a URL like https://github.com/expressjs/express
• Drag & drop — just drop a folder onto the page

That's it. You'll get your report in a few seconds.

---

What it actually does

1. Scans your files

It reads through your project and classifies every file by language, role (source, config, test, infra), and whether it looks like an entry point. The usual suspects are ignored automatically node_modules, .git, dist, lock files, images, binaries, anything over 1MB.

Two sources are supported:

• Local folder - uses the File System Access API on Chrome/Edge, falls back to <input webkitdirectory> on Firefox/Safari
• GitHub - fetches the file tree via the Git Trees API, then grabs file contents in batches

2. Analyzes the code

Five language-specific analyzers extract structure from the source:

• JS/TS - ES imports, CommonJS requires, dynamic imports, functions, classes, Express/Koa routes, process.env references, data store access (Mongoose, Prisma, Redis, etc.)
• Python - imports, function/class defs, Flask/FastAPI/Django routes, os.environ / os.getenv, security patterns
• Java - packages, imports, classes, methods, Spring annotations (@RestController, @GetMapping, etc.)
• Shell - .env file parsing, script sourcing, env var references, service invocations (docker, kubectl, curl)
• Config - package.json deep analysis, Docker Compose services, K8s manifests, GitHub Actions workflows, Maven POM, Spring config

Each analyzer also estimates cyclomatic complexity per file, and computes things like instability, maintainability index, and a tech debt score.

3. Runs detectors

Six detectors run graph-level analysis looking for problems:

Detector	What it looks for
Cycles	Circular dependencies between files (Tarjan's SCC)
Dead Code	Files with zero incoming references, unreachable from entry points
Config Sprawl	Env vars read from 4+ files, orphaned vars, missing definitions
Coupling	Files with >15 inbound or outbound dependencies
Chokepoints	Modules where >30% of system paths converge — single points of failure
Security	Hardcoded secrets, eval(), disabled TLS, command injection, unsafe deserialization

Findings are tagged with CWE IDs where applicable.

4. Generates the report

Everything gets bundled into a single self-contained HTML file — no external dependencies, no network calls. You can save it, email it, drop it in a wiki, whatever. The report includes:

• Map - force-directed graph with pan, zoom, click-to-inspect, minimap, folder clustering
• Findings - all issues grouped by category with severity, CWE links, and remediation advice
• Workflow - inferred flow from entry points → handlers → services → data stores
• Dashboard - health score, metrics breakdown, language distribution
• Search - fuzzy search across all nodes
• Export - download findings as TXT, CSV, or PDF

---

The Report

Health Score

The report shows a letter grade based on findings:

Score = max(0, 100 − criticals × 15 - errors × 8 - warnings × 3)

Grade	Score Range
A	90-100
B	75-89
C	60-74
D	40-59
F	0-39

Inspect Panel

Click any node in the graph to see:

• Fan-in / fan-out metrics, complexity, instability, maintainability index
• Direct dependencies and dependents
• Coupling impact (what breaks if this file changes)
• Related findings and security issues

---

Supported Languages

Language	Extensions
JavaScript	.js .jsx .mjs .cjs
TypeScript	.ts .tsx .mts .cts
Python	.py .pyw
Java	.java
Shell	.sh .bash .bat .cmd .ps1
YAML	.yml .yaml
JSON	.json .jsonc
XML	.xml .pom .wsdl
SQL	.sql
CSS/HTML	.css .scss .html
Dockerfile	Dockerfile Containerfile
Markdown	.md .mdx .rst

---

GitHub API Notes

When scanning a GitHub repo, requests go directly from your browser to api.github.com.

• Without a token - 60 requests/hour, public repos only
• With a token - 5,000 requests/hour, private repos supported

To create a token: GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens. You only need repo (read) scope.

Your token is never stored or sent anywhere except directly to GitHub's API.

---

Browser Support

Browser	Directory Picker	Fallback	GitHub	Drag & Drop
Chrome 86+	✅	✅	✅	✅
Edge 86+	✅	✅	✅	✅
Firefox	❌	✅	✅	✅
Safari 15.2+	❌	✅	✅	✅

Chrome and Edge give the best experience since they support the native directory picker.

---

Project Structure

├── src/
│   ├── main.ts                    # App entry point, UI, pipeline orchestration
│   ├── index.html                 # Landing page
│   ├── scanner/
│   │   ├── local-source.ts        # File System Access API + webkitdirectory fallback
│   │   ├── github-source.ts       # GitHub REST API scanner
│   │   └── filters.ts             # File/folder ignore rules
│   └── core/
│       ├── graph/model.ts         # Core types: GraphNode, GraphEdge, Finding, CodeFlowGraph
│       ├── scanner/
│       │   ├── classify.ts        # File classification by extension & patterns
│       │   └── discover.ts        # DiscoveredFile & ScanResult types
│       ├── analyzers/
│       │   ├── index.ts           # Analyzer pipeline
│       │   ├── js-ts-analyzer.ts  # JavaScript/TypeScript
│       │   ├── python-analyzer.ts # Python
│       │   ├── java-analyzer.ts   # Java
│       │   ├── shell-analyzer.ts  # Shell & .env files
│       │   └── config-analyzer.ts # YAML/JSON/XML configs
│       ├── detectors/
│       │   ├── index.ts           # Detector pipeline
│       │   ├── cycles.ts          # Circular dependency detection (Tarjan SCC)
│       │   ├── dead-code.ts       # Dead code detection (BFS reachability)
│       │   ├── config-sprawl.ts   # Config sprawl analysis
│       │   ├── coupling.ts        # Coupling metrics
│       │   ├── chokepoints.ts     # Chokepoint detection (path centrality)
│       │   ├── security.ts        # Security pattern matching
│       │   └── rule-engine.ts     # Custom rule evaluation
│       └── report/
│           └── build-report.ts    # Self-contained HTML report generator
├── build.js                       # esbuild config
├── package.json
├── tsconfig.json
└── LICENSE

---

Development

# Watch mode - rebuilds on every save
npm run dev

# Type check
npx tsc --noEmit

# Production build (minified)
npm run build

# Serve locally
npm run serve

---

Privacy

All analysis runs locally in your browser. No code is uploaded, no telemetry, no tracking, no accounts. GitHub API calls (when you choose that source) go directly from your browser the app has no backend. The generated report is a standalone HTML file with zero external dependencies.

---

Contributing

Contributions are welcome. Here's the flow:

1. Fork the repo
2. Create a branch (git checkout -b feature/my-thing)
3. Make sure npx tsc --noEmit passes and npm run build succeeds
4. Open a PR

Some ideas if you're looking for something to work on:

• New language analyzers - Go, Rust, C#, PHP, Ruby
• More detectors - complexity hotspots, test coverage gaps, dependency age
• CI integration - run SysNexus as a GitHub Action
• Static hosting - deploy to GitHub Pages / Netlify / Vercel

---

License

MIT - do whatever you want with it.

---

See your system. Understand it. Improve it.