How chethan13032005/vi-notes works
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: App.tsx App Shell · session.js Session Routes · session.controller.ts Session Controller · index.js API Server
Components 22
Client App
React/Electron interface for authentication, writing capture, replay, and public certificate viewing.
- Electron · Launches the client as a desktop app.
client/electron.js - App Shell · Client navigation and page composition.
client/src/App.tsx - Login · Handles sign-in and registration flow.
client/src/Components/Login.tsx - Editor · Records typing behavior, pauses, and paste events.
client/src/Components/Editor.tsx - Session List · Shows saved sessions and share state.
client/src/Components/SessionList.tsx - Replay Player · Reconstructs text production over time.
client/src/Components/ReplayPlayer.tsx - Certificate View · Displays shared-session proof and verification details.
client/src/pages/CertificateView.tsx - Contracts · Client-side API and data contracts.
client/src/types/contracts.ts
Backend API
Express service handling auth, session persistence, and public verification.
- API Server · Main HTTP entrypoint and route wiring.
server/index.js - Auth Routes · Public registration and login endpoints.
server/routes/auth.js - Session Routes · Protected session save, list, and share endpoints.
server/routes/session.js - Verify Route · Public certificate lookup by certificate ID.
server/routes/verify.js - Require Auth · JWT protection boundary for private session operations.
server/middleware/requireAuth.js - Session Controller · Coordinates session requests and analysis responses.
server/controllers/session.controller.ts - Session Model · Stores writing content, metadata, analysis, and share state.
server/models/Session.js - User Model · Stores accounts and auth identity.
server/models/User.js
Analysis Pipeline
Server-side validation and scoring flow that produces authenticity signals.
- Validate Payload · Checks raw session data before analysis.
server/utils/validateRawSessionData.js - Feature Extractor · Derives behavioral and textual features.
server/ml/featureExtractor.js - Analyzer · Combines ML and rule-based analysis into a report.
server/ml/analyzer.js - Segment Detector · Marks normal, copied, and ai_suspect regions.
server/ml/segmentDetector.js - TensorFlow Adapter · Placeholder adapter for future model-based scoring.
server/ml/adapters/tensorflowAdapter.js - Analyze Helper · Utility wrapper that runs the analysis pipeline.
server/utils/analyze.js
Connections 31
- 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.