# chethan13032005/vi-notes architecture

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

- Interactive diagram: https://gitdiagram.com/chethan13032005/vi-notes
- Repository: https://github.com/chethan13032005/vi-notes

## Overview

Vi-Notes is a two-tier authenticity verification system with a React/Electron client and a Node/Express/MongoDB backend. The core architectural idea is that the client captures writing behavior as structured metadata, the server analyzes that metadata into an authenticity report, and a separate public verification path exposes a shareable certificate view.

Main subsystems

1. Client application
- Built with React + TypeScript using the CRA toolchain.
- Routed pages include:
  - /login and /register for authentication
  - /dashboard for the main writing workflow
  - /verify/:certificateId for the public certificate page
- Key UI components:
  - Login: handles auth flow
  - Editor: the distraction-free writing surface that records keystrokes, delays, and paste events
  - SessionList: shows saved sessions and share/private state
  - ReplayPlayer: replays how the text was produced over time
  - CertificateView: public proof page for shared sessions
- There is also an Electron entry point in client/electron.js, so the same frontend can be launched as a desktop app, not only in the browser.

2. Backend API server
- Built on Node.js + Express.
- Uses JWT-based authentication.
- Persists data in MongoDB through Mongoose models.
- Primary API areas:
  - Auth routes: register/login
  - Session routes: save a writing session, list a user’s sessions, share a session
  - Verify route: public lookup by certificate ID
- The requireAuth middleware forms the main security boundary for protected session operations.

3. Analysis pipeline
- The server includes a dedicated analysis stack under server/ml and related utility files.
- The pipeline is layered:
  - Validate incoming session payloads
  - Extract behavioral and textual features
  - Attempt ML-based analysis via a TensorFlow adapter placeholder
  - Fall back to rule-based scoring and segment detection
- Segment labels used by the app include:
  - normal
  - copied
  - ai_suspect
- The analysis output includes a score, reasons, statistics, and highlighted ranges.

Data flow through the system

1. User authentication
- The user registers or logs in from the client.
- The backend returns a JWT token.
- The client uses that token for protected dashboard/session API calls.

2. Writing capture in the editor
- In the dashboard editor, the client records:
  - typed text
  - keystroke timing / rhythm
  - editing pauses and corrections
  - paste event ranges
- The README emphasizes that the system does not log raw key content; it focuses on metadata and behavioral signals.

3. Session save and analysis
- When the user saves a session, the client sends the text plus metadata to the server.
- The backend validates the raw session data, runs the analysis pipeline, and stores the result in MongoDB.
- The response contains the session ID plus analysis output such as score, reasons, and segments.
- The client then uses that analysis to render the authenticity report and detection visualization.

4. Replay and review
- The ReplayPlayer reconstructs the writing timeline from timing metadata.
- Typed text appears progressively.
- Pasted text appears as a single chunk at the paste moment.
- Highlighting differentiates copied and suspicious regions from normal writing.

5. Sharing and public verification
- When a session is shared, the backend marks it public and generates a certificate ID.
- The dashboard updates immediately to reflect the shared state.
- The public /verify/:certificateId route retrieves the shared session without requiring authentication.
- The CertificateView displays the score, metrics, replay, and proof link for external review.

Important boundaries

- Auth boundary: register/login are public; session list, save, and share are protected by JWT.
- Public verification boundary: certificate lookup is intentionally public, but only for sessions explicitly shared.
- Analysis boundary: client captures behavior; server is the source of truth for scoring and segment labeling.
- Persistence boundary: MongoDB stores users and sessions, while the client only holds state needed for rendering and interaction.

Data model and persistence

- User model: accounts and auth identity.
- Session model: writing content, keystroke metadata, paste metadata, analysis results, and share/public state.
- The public certificate is not a separate product area so much as a view over a shared session record.

Technology choices that matter architecturally

- React + React Router drive the client-side navigation and page composition.
- TypeScript is used on the client and appears in parts of the server tree as well, suggesting a mixed or transitional codebase.
- Express provides the API layer and route separation.
- JWT provides stateless auth for protected operations.
- MongoDB/Mongoose provide document storage for sessions and users.
- Electron adds a desktop deployment path for the same UI.
- TensorFlow is present as an adapter layer, but the current analysis behavior is still rule-driven, which means the architecture is prepared for ML upgrades without changing API contracts.

Repository structure implications

- The client is organized by feature/component rather than by low-level infrastructure.
- The server is split into routes, middleware, models, utilities, and a dedicated analysis package.
- The presence of both JS and TS files in the server tree suggests an evolving backend implementation rather than a purely single-language codebase.

In diagram form, the core picture is:
user input in Editor -> metadata capture in client -> authenticated save to Express API -> validation and analysis pipeline -> MongoDB session persistence -> report/replay rendering in client, with a separate public certificate retrieval path for shared sessions.

Main entry points: [`client/src/App.tsx`](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/App.tsx) (App Shell), [`server/routes/session.js`](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/routes/session.js) (Session Routes), [`server/controllers/session.controller.ts`](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/controllers/session.controller.ts) (Session Controller), [`server/index.js`](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/index.js) (API Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Client App"
  electron["Electron<br/>desktop entry<br/>[electron.js]"]
  app["App Shell<br/>React router<br/>[App.tsx]"]
  login["Login<br/>auth UI<br/>[Login.tsx]"]
  editor["Editor<br/>capture UI<br/>[Editor.tsx]"]
  sessions["Session List<br/>dashboard UI<br/>[SessionList.tsx]"]
  replay["Replay Player<br/>timeline UI<br/>[ReplayPlayer.tsx]"]
  certview["Certificate View<br/>public page"]
  contracts["Contracts<br/>shared types<br/>[contracts.ts]"]
end

subgraph "Backend API"
  api["API Server<br/>Express app<br/>[index.js]"]
  authroutes["Auth Routes<br/>[auth.js]"]
  sessionroutes["Session Routes<br/>[session.js]"]
  verifyroutes["Verify Route<br/>public route<br/>[verify.js]"]
  authmw{{"Require Auth<br/>middleware<br/>[requireAuth.js]"}}
  sessionctrl["Session Controller"]
  sessionmodel[("Session Model<br/>mongoose model<br/>[Session.js]")]
  usermodel[("User Model<br/>mongoose model<br/>[User.js]")]
end

subgraph "Analysis Pipeline"
  validate["Validate Payload"]
  features["Feature Extractor<br/>analysis step"]
  analyzer["Analyzer<br/>scoring engine<br/>[analyzer.js]"]
  segment["Segment Detector<br/>labeler<br/>[segmentDetector.js]"]
  tfadapter["TensorFlow Adapter<br/>ml adapter"]
  analyzeutil["Analyze Helper<br/>[analyze.js]"]
end

electron -->|"launches"| app
app -->|"routes"| login
app -->|"routes"| editor
app -->|"routes"| sessions
app -->|"renders"| replay
app -->|"routes"| certview
editor -->|"uses"| contracts
sessions -->|"uses"| contracts
replay -->|"uses"| contracts
certview -->|"uses"| contracts
login -->|"auth"| api
editor -->|"save session"| sessionroutes
sessions -->|"list/share"| sessionroutes
certview -->|"lookup"| verifyroutes
api -->|"mounts"| authroutes
api -->|"mounts"| sessionroutes
api -->|"mounts"| verifyroutes
sessionroutes -->|"guards"| authmw
sessionroutes -->|"delegates"| sessionctrl
authroutes -->|"uses"| usermodel
sessionctrl -->|"validates"| validate
sessionctrl -->|"analyzes"| analyzeutil
analyzeutil -->|"extracts"| features
features -->|"feeds"| analyzer
analyzer -->|"attempts ml"| tfadapter
analyzer -->|"labels"| segment
analyzer -->|"writes report"| sessionmodel
sessionctrl -->|"persists"| sessionmodel
sessionctrl -->|"links"| usermodel
verifyroutes -->|"reads public"| sessionmodel
sessionroutes -->|"returns"| api

click electron "https://github.com/chethan13032005/vi-notes/blob/main/client/electron.js"
click app "https://github.com/chethan13032005/vi-notes/blob/main/client/src/App.tsx"
click login "https://github.com/chethan13032005/vi-notes/blob/main/client/src/Components/Login.tsx"
click editor "https://github.com/chethan13032005/vi-notes/blob/main/client/src/Components/Editor.tsx"
click sessions "https://github.com/chethan13032005/vi-notes/blob/main/client/src/Components/SessionList.tsx"
click replay "https://github.com/chethan13032005/vi-notes/blob/main/client/src/Components/ReplayPlayer.tsx"
click certview "https://github.com/chethan13032005/vi-notes/blob/main/client/src/pages/CertificateView.tsx"
click contracts "https://github.com/chethan13032005/vi-notes/blob/main/client/src/types/contracts.ts"
click api "https://github.com/chethan13032005/vi-notes/blob/main/server/index.js"
click authroutes "https://github.com/chethan13032005/vi-notes/blob/main/server/routes/auth.js"
click sessionroutes "https://github.com/chethan13032005/vi-notes/blob/main/server/routes/session.js"
click verifyroutes "https://github.com/chethan13032005/vi-notes/blob/main/server/routes/verify.js"
click authmw "https://github.com/chethan13032005/vi-notes/blob/main/server/middleware/requireAuth.js"
click sessionctrl "https://github.com/chethan13032005/vi-notes/blob/main/server/controllers/session.controller.ts"
click sessionmodel "https://github.com/chethan13032005/vi-notes/blob/main/server/models/Session.js"
click usermodel "https://github.com/chethan13032005/vi-notes/blob/main/server/models/User.js"
click validate "https://github.com/chethan13032005/vi-notes/blob/main/server/utils/validateRawSessionData.js"
click features "https://github.com/chethan13032005/vi-notes/blob/main/server/ml/featureExtractor.js"
click analyzer "https://github.com/chethan13032005/vi-notes/blob/main/server/ml/analyzer.js"
click segment "https://github.com/chethan13032005/vi-notes/blob/main/server/ml/segmentDetector.js"
click tfadapter "https://github.com/chethan13032005/vi-notes/blob/main/server/ml/adapters/tensorflowAdapter.js"
click analyzeutil "https://github.com/chethan13032005/vi-notes/blob/main/server/utils/analyze.js"

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 electron,app,login,editor,sessions,replay,certview,contracts toneBlue
class api,authroutes,sessionroutes,verifyroutes,authmw,sessionctrl,sessionmodel,usermodel toneAmber
class validate,features,analyzer,segment,tfadapter,analyzeutil toneMint
```

## Components

### Client App

React/Electron interface for authentication, writing capture, replay, and public certificate viewing.

- [Electron](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/electron.js): desktop entry · Launches the client as a desktop app. · `client/electron.js`
- [App Shell](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/App.tsx): React router · Client navigation and page composition. · `client/src/App.tsx`
- [Login](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/Components/Login.tsx): auth UI · Handles sign-in and registration flow. · `client/src/Components/Login.tsx`
- [Editor](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/Components/Editor.tsx): capture UI · Records typing behavior, pauses, and paste events. · `client/src/Components/Editor.tsx`
- [Session List](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/Components/SessionList.tsx): dashboard UI · Shows saved sessions and share state. · `client/src/Components/SessionList.tsx`
- [Replay Player](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/Components/ReplayPlayer.tsx): timeline UI · Reconstructs text production over time. · `client/src/Components/ReplayPlayer.tsx`
- [Certificate View](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/pages/CertificateView.tsx): public page · Displays shared-session proof and verification details. · `client/src/pages/CertificateView.tsx`
- [Contracts](https://github.com/chethan13032005/vi-notes/blob/HEAD/client/src/types/contracts.ts): shared types · Client-side API and data contracts. · `client/src/types/contracts.ts`

### Backend API

Express service handling auth, session persistence, and public verification.

- [API Server](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/index.js): Express app · Main HTTP entrypoint and route wiring. · `server/index.js`
- [Auth Routes](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/routes/auth.js): route · Public registration and login endpoints. · `server/routes/auth.js`
- [Session Routes](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/routes/session.js): route · Protected session save, list, and share endpoints. · `server/routes/session.js`
- [Verify Route](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/routes/verify.js): public route · Public certificate lookup by certificate ID. · `server/routes/verify.js`
- [Require Auth](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/middleware/requireAuth.js): middleware · JWT protection boundary for private session operations. · `server/middleware/requireAuth.js`
- [Session Controller](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/controllers/session.controller.ts): controller · Coordinates session requests and analysis responses. · `server/controllers/session.controller.ts`
- [Session Model](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/models/Session.js): mongoose model · Stores writing content, metadata, analysis, and share state. · `server/models/Session.js`
- [User Model](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/models/User.js): mongoose model · Stores accounts and auth identity. · `server/models/User.js`

### Analysis Pipeline

Server-side validation and scoring flow that produces authenticity signals.

- [Validate Payload](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/utils/validateRawSessionData.js): utility · Checks raw session data before analysis. · `server/utils/validateRawSessionData.js`
- [Feature Extractor](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/ml/featureExtractor.js): analysis step · Derives behavioral and textual features. · `server/ml/featureExtractor.js`
- [Analyzer](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/ml/analyzer.js): scoring engine · Combines ML and rule-based analysis into a report. · `server/ml/analyzer.js`
- [Segment Detector](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/ml/segmentDetector.js): labeler · Marks normal, copied, and ai_suspect regions. · `server/ml/segmentDetector.js`
- [TensorFlow Adapter](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/ml/adapters/tensorflowAdapter.js): ml adapter · Placeholder adapter for future model-based scoring. · `server/ml/adapters/tensorflowAdapter.js`
- [Analyze Helper](https://github.com/chethan13032005/vi-notes/blob/HEAD/server/utils/analyze.js): utility · Utility wrapper that runs the analysis pipeline. · `server/utils/analyze.js`

## Connections

- Electron → App Shell: launches · Desktop entry starts the same frontend UI.
- App Shell → Login: routes · Navigates to auth pages.
- App Shell → Editor: routes · Main dashboard writing surface.
- App Shell → Session List: routes · Session overview and sharing state.
- App Shell → Replay Player: renders · Replay and review view.
- App Shell → Certificate View: routes · Public certificate page.
- Editor → Contracts: uses · Shares request and session shapes.
- Session List → Contracts: uses · Consumes session and share-state contracts.
- Replay Player → Contracts: uses · Consumes replay payload shapes.
- Certificate View → Contracts: uses · Consumes certificate view data.
- Login → API Server: auth · Registers and logs in against the backend.
- Editor → Session Routes: save session · Sends text and behavior metadata for analysis.
- Session List → Session Routes: list/share · Loads sessions and toggles public sharing.
- Certificate View → Verify Route: lookup · Fetches shared session by certificate ID.
- API Server → Auth Routes: mounts · Exposes authentication endpoints.
- API Server → Session Routes: mounts · Exposes protected session endpoints.
- API Server → Verify Route: mounts · Exposes public verification endpoint.
- Session Routes → Require Auth: guards · Protects session save/list/share operations.
- Session Routes → Session Controller: delegates · Hands off business logic to controller.
- Auth Routes → User Model: uses · Creates and authenticates users.
- Session Controller → Validate Payload: validates · Checks raw payload before scoring.
- Session Controller → Analyze Helper: analyzes · Runs the authenticity pipeline.
- Analyze Helper → Feature Extractor: extracts · Builds features from text and behavior.
- Feature Extractor → Analyzer: feeds · Provides derived signals for scoring.
- Analyzer → TensorFlow Adapter: attempts ml · Tries model-based analysis first.
- Analyzer → Segment Detector: labels · Produces normal/copied/ai_suspect ranges.
- Analyzer → Session Model: writes report · Stores score, reasons, stats, and segments.
- Session Controller → Session Model: persists · Saves session records and share state.
- Session Controller → User Model: links · Associates sessions with authenticated users.
- Verify Route → Session Model: reads public · Fetches only shared sessions for verification.
- Session Routes → API Server: returns · Responds with saved session IDs and analysis output.
