Flowchart Synthesizer

A voice-activated, AI-powered application that converts unstructured spoken or typed thoughts into clean, structured flowcharts. Speak through a process, idea, or logic sequence, and the application transcribes your speech, sends it to Google's Gemini model, and renders a Mermaid.js diagram in real time.

Overview

Flowchart Synthesizer solves a simple problem: turning messy, stream-of-consciousness thinking into structured visual documentation without manual diagramming. It uses the browser's native speech recognition to capture dictation, a secure Node.js backend to communicate with the Gemini API, and Mermaid.js to render the resulting flowchart directly in the browser.

The project is intentionally built as a full stack application, separating the public-facing frontend from a backend server that holds the API key. This keeps the Gemini API key private and out of any client-side code or public repository.

Features

• Voice dictation using the browser's Web Speech API, with a manual text input as a fallback
• Real-time transcription with live status feedback (listening, errors, permissions)
• AI-powered synthesis of unstructured text into valid Mermaid.js flowchart syntax
• Automatic cleanup of AI output to prevent common rendering failures
• Secure backend architecture that keeps the API key hidden from the browser
• Simple, dependency-light frontend built with vanilla HTML, CSS, and JavaScript

Architecture

The application is split into two independent pieces that communicate over HTTP:

Frontend (index.html) Runs entirely in the browser. Handles microphone access and speech-to-text transcription, displays the transcript in an editable text box, and sends the finished text to the backend when the user clicks "Generate Flowchart." It also renders the returned Mermaid.js code as a visual diagram.

Backend (server.js) A lightweight Node.js and Express server. It receives the transcribed text from the frontend, attaches the system prompt and the private API key, and forwards the request to the Gemini API. It then cleans the AI's response and returns only the flowchart syntax to the frontend. The API key never leaves the server and is never exposed to the browser.

Browser (Mic + UI)  --text-->  Node.js/Express Server  --text + key-->  Gemini API
Browser (Mic + UI)  <--chart--  Node.js/Express Server  <--chart-------  Gemini API

How It Works, Step by Step

1. The user clicks "Start Recording" and speaks a messy, unstructured thought.
2. The Web Speech API transcribes the audio into text in real time and displays it in a text box.
3. The user clicks "Generate Flowchart."
4. The frontend sends the raw text to the backend endpoint /api/generate.
5. The backend combines the text with a strict system prompt instructing the model to output only valid Mermaid.js syntax, then calls the Gemini API.
6. The backend strips any markdown code fences or formatting artifacts from the model's response.
7. The cleaned Mermaid.js syntax is sent back to the frontend.
8. Mermaid.js renders the syntax as a visual flowchart directly on the page.

Tech Stack

Layer	Technology
Frontend	HTML5, CSS3, Vanilla JavaScript
Speech Recognition	Web Speech API (browser native)
Diagram Rendering	Mermaid.js
Backend	Node.js, Express.js
AI Model	Google Gemini 2.5 Flash
Environment Management	dotenv

Project Structure

flowchart-synth/
├── index.html          Frontend UI, speech recognition, and rendering logic
├── server.js            Express backend that talks securely to Gemini
├── package.json          Node dependencies and project metadata
├── package-lock.json     Locked dependency versions
├── .env                  Local environment file holding the API key (not committed)
├── .gitignore            Excludes .env and node_modules from version control
└── README.md             Project documentation

Prerequisites

• Node.js and npm installed on your machine
• A Google Gemini API key, available from Google AI Studio
• A Chromium-based browser (Google Chrome or Microsoft Edge) for speech recognition support
• The VS Code Live Server extension, or any static file server, to serve the frontend

Setup and Installation

1. Clone the Repository

git clone https://github.com/Shikhar-2005/Flowchart-Synth.git
cd Flowchart-Synth

2. Install Dependencies

npm install

This installs Express, CORS, dotenv, and the Google Generative AI SDK.

3. Configure Environment Variables

Create a file named .env in the project root and add your Gemini API key:

GEMINI_API_KEY=your_actual_api_key_here

This file is excluded from version control by .gitignore and should never be committed or shared publicly.

4. Run the Backend

node server.js

The server will start and listen on http://localhost:3000.

5. Run the Frontend

Open index.html using a local static server, such as the "Go Live" button in VS Code's Live Server extension. This will open the application in your browser, typically at http://localhost:5500 or http://127.0.0.1:5500.

Both the backend and the frontend must be running at the same time for the application to work.

Usage

1. With both servers running, open the frontend in Chrome or Edge.
2. Click "Start Recording" and allow microphone access when prompted.
3. Speak your process or idea out loud, or type it directly into the text box.
4. Click "Generate Flowchart."
5. The application will send your text to the backend, which queries Gemini and returns structured flowchart syntax, rendered instantly as a diagram.

If the AI occasionally returns malformed syntax that fails to render, simply click "Generate Flowchart" again or slightly rephrase your input. This is a normal characteristic of generative AI output rather than a bug in the application.

Security Considerations

• The Gemini API key is stored only in the local .env file and read exclusively by the backend server.
• The key is never sent to, stored in, or accessible from the browser or any client-side JavaScript.
• .gitignore explicitly excludes .env and node_modules/ from being committed to the repository.
• Anyone cloning this repository must supply their own API key to run the application; no key is bundled with the source code.

Known Limitations

• The Web Speech API is only reliably supported in Chromium-based browsers.
• Speech recognition requires an active internet connection, since transcription is processed on external servers rather than locally.
• Mermaid.js rendering can occasionally fail if the AI produces invalid syntax; a retry or rephrased input typically resolves this.
• The application currently runs locally and has not been configured for production deployment or hosting.

Potential Future Improvements

• Deploy the backend to a hosting platform (such as Render, Railway, or Heroku) and the frontend to a static host, enabling public access without local setup.
• Add support for exporting generated flowcharts as image or PDF files.
• Introduce user accounts to save and revisit previously generated flowcharts.
• Expand language support for speech recognition beyond English.
• Add a retry mechanism that automatically re-requests a chart from the AI if rendering fails.

License

This project is open for personal and educational use. Feel free to fork, modify, and build upon it.

Acknowledgments

• Google Gemini API for natural language processing and text generation.
• Mermaid.js for diagram rendering.
• The Web Speech API for browser-native voice transcription.