Skip to content

Commit 9bed9e1

Browse files
PraneethKulukuri26PraneethKulukuri26
committed
docs: add developer guide, update project documentation and metadata to version 1.0.24
1 parent 939fd08 commit 9bed9e1

4 files changed

Lines changed: 218 additions & 111 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Thank you for your interest in contributing to API Documenter! We welcome contri
1818
2. Run `npm install`.
1919
3. Run `npm run dev` to start the development environment.
2020

21+
> 📚 **Important:** Before diving into the codebase, please read our [Developer Guide](DEVELOPER.md) to understand the project architecture, Git integration, and Sync Queue engine.
22+
2123
## Style Guidelines
2224

2325
- Use TypeScript for all new code.

‎DEVELOPER.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# API Documenter: Developer Guide
2+
3+
Welcome to the API Documenter source code! This guide explains the core architecture, the folder structure, and how the advanced features (like the Git integration and Sync Engine) work under the hood.
4+
5+
## 🏗️ Core Architecture
6+
7+
API Documenter is a local-first, hybrid-sync application built with the **Electron** framework. It consists of three distinct layers:
8+
9+
1. **Frontend (Renderer Process):** Built with React 18, Vite, Tailwind CSS, Zustand (state), and React Query. It stores data locally in IndexedDB (using Dexie.js) to guarantee offline availability and instant UI response.
10+
2. **Desktop Core (Main Process):** Handles file system operations, local Git interactions, direct MySQL/PostgreSQL connections (Local Mode), and IPC bridging.
11+
3. **Remote Proxy (Vercel):** A serverless Node.js application deployed to Vercel that handles Role-Based Access Control (RBAC) and team collaboration (Team Workspace Mode).
12+
13+
---
14+
15+
## 📂 Project Structure
16+
17+
Here is a breakdown of the codebase to help you navigate:
18+
19+
### `/src` (Electron App)
20+
* **`/src/main` (Main Process)**
21+
* `index.ts`: The main entry point for the Electron app. Manages window lifecycle.
22+
* **`/controllers/`**: Contains the logic that runs securely in Node.js.
23+
* `SyncController.ts`: Handles direct connections to your remote MySQL/Postgres database and processes the `sync_queue` for Local Mode syncing.
24+
* `GitController.ts`: Exposes Git operations to the frontend via IPC.
25+
* `gitManager.ts`: A wrapper around `simple-git` that executes Git commands (commit, checkout, branch) on your local workspace.
26+
* `fileWatcher.ts`: Monitors your local directory for changes to `.apidoc`, `.folder`, and `.json` schema files.
27+
* **`/src/preload`**
28+
* `index.ts`: Context Bridge exposing safe IPC methods (like `window.electronAPI.sendHttpRequest` and `window.electronAPI.fetchSyncQueue`) to the React frontend.
29+
* **`/src/renderer` (React Frontend)**
30+
* **`/src/components/`**: React components. The heart of the UI.
31+
* `Sidebar.tsx`: Renders the folder tree, sync buttons, and Git status indicators.
32+
* `ApiDocumentationPage.tsx`: The main Markdown editor, request builder, and response viewer.
33+
* **`/src/hooks/`**: Data fetching and business logic.
34+
* `useSync.ts`: The complex sync engine. Pulls items from the proxy/db, resolves conflicts, and manages push queues.
35+
* `useGit.ts`: Connects UI actions to the underlying `GitManager`.
36+
* **`/src/db/`**: Contains the `Dexie.js` configuration for Local IndexedDB storage.
37+
* **`/src/stores/`**: Zustand state management (e.g., `appStore.ts` for tracking the active branch and team configurations).
38+
39+
### `/server` (Proxy Server)
40+
This is the deployable Vercel serverless backend for Team Workspaces.
41+
* **`/server/src/db/`**: Adapters for MySQL and Postgres. Includes the `schema.sql` file used to initialize the databases.
42+
* **`/server/src/middleware/`**:
43+
* `rbac.ts`: Enforces the Admin/Editor/Viewer roles at the folder and environment levels.
44+
* **`/server/routes/`**: API endpoints.
45+
* `/sync.ts`: Handles the exact same queue-processing logic as `SyncController.ts` but enforces RBAC and user tokens.
46+
* `/apis`, `/folders`, `/users`: Standard CRUD endpoints for the team workspace.
47+
48+
---
49+
50+
## 🌿 The Git Integration (Developer-Friendly Version Control)
51+
52+
API Documenter treats your API specifications as code. You can version control your API endpoints exactly like source code.
53+
54+
### How it works:
55+
1. **Local Storage:** When you create an API or Folder, the app not only saves it to the local IndexedDB but also writes it as a physical file (e.g., `login.apidoc`, `auth.folder`) in your selected local workspace directory.
56+
2. **File Watcher (`src/main/fileWatcher.ts`):** A `chokidar` file watcher monitors your local workspace. If you edit a `.apidoc` file externally in VS Code, or pull changes via Git CLI, the File Watcher instantly detects the change, parses the JSON, and updates the local IndexedDB.
57+
3. **Git Manager (`src/main/gitManager.ts`):** The app uses `simple-git` to allow you to perform standard Git operations from within the API Documenter UI:
58+
* **Branches:** Create new branches for experimental API designs without affecting the `master` documentation.
59+
* **Commits:** Stage and commit your `.apidoc` files. The app intelligently maps the files you've modified and links them to the commit.
60+
* **Discard:** Revert uncommitted changes, instantly restoring the previous state in both the filesystem and the UI.
61+
62+
### Why this is developer-friendly:
63+
By syncing both to a Database AND tracking files via Git, you get the best of both worlds: Non-technical team members can view real-time API docs from the database, while developers can submit PRs to update API documentation right alongside their backend code.
64+
65+
---
66+
67+
## 🔄 The Sync Engine & Offline Queue
68+
69+
API Documenter is **offline-first**.
70+
71+
When you lose internet connection, you can still read, edit, create, and delete APIs.
72+
* **The Sync Queue:** Every action you take is logged into a local IndexedDB table called `syncQueue` (storing the operation type: `create`, `update`, `delete`).
73+
* **Pushing:** When you click "Sync" (or the auto-sync triggers), `useSync.ts` gathers all pending operations and sends them to either `SyncController.ts` (Local DB mode) or `server/routes/sync.ts` (Proxy mode).
74+
* **Conflict Resolution:** If the remote database has a newer `version` of the API than your local machine, the server returns a `conflict`. The UI deduplicates these conflicts and presents a dialog asking you to either "Keep My Changes" or "Accept Remote".
75+
* **Auto-Resolution:** The sync engine is smart enough to auto-resolve identical duplicate operations or ignore ghost edits on APIs that have already been deleted.
76+
77+
---
78+
79+
## 🚀 Getting Started with Development
80+
81+
1. Run `npm install` in the root directory.
82+
2. Run `npm run dev` to start the Electron + Vite process.
83+
3. Use the Chrome DevTools (Ctrl+Shift+I) in the Electron window to debug the React frontend.
84+
4. Main process logs will appear in your terminal.

‎README.md‎

Lines changed: 130 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -1,109 +1,130 @@
1-
<div align="center">
2-
<img src="resources/icon.jpg" alt="API Documenter Logo" width="128" />
3-
4-
# API Documenter
5-
### The Professional Self-Hosted API Ecosystem
6-
7-
**Postman Power + Enterprise Control + 100% Data Ownership.**
8-
9-
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10-
[![Version](https://img.shields.io/badge/version-1.0.20-emerald.svg)](package.json)
11-
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
12-
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS-lightgrey.svg)](#)
13-
</div>
14-
15-
---
16-
17-
## 🌟 The Vision
18-
19-
**API Documenter** is more than just an API client; it is a complete **Documentation and Testing Ecosystem**. It was built for engineering teams that cannot compromise on data privacy or reliability. While existing tools force your sensitive API keys and internal endpoints onto their cloud, API Documenter keeps your data exactly where it belongs: **on your machine and in your private database.**
20-
21-
---
22-
23-
## 🚀 Master Feature Suite
24-
25-
### 1. 📂 Folder-Level RBAC (Enterprise Security)
26-
The first self-hosted tool to offer granular, folder-level **Role Based Access Control**.
27-
- **Admins**: Manage project connections, deployment settings, and global team permissions.
28-
- **Editors**: Create and modify endpoints within specific folders they have access to.
29-
- **Viewers**: Access real-time documentation and test endpoints without risk of modifying team data.
30-
- **Team Isolation**: Different members can have different roles on different folders within the same project.
31-
32-
### 2. 📝 Advanced Documentation Engine
33-
A dedicated workspace for crafting beautiful, production-ready API documentation.
34-
- **Markdown-Native**: Write documentation using standard Markdown with real-time side-by-side preview.
35-
- **Smart Components**: Insert **Smart Table of Contents**, **Page Breaks**, and dynamic code blocks.
36-
- **Built-in PDF Compilation**: Export high-fidelity A4 documentation PDFs using a built-in Chromium engine (no external Chrome dependency required).
37-
- **Distraction-Free Mode**: Collapse all sidebars and toolbars to focus purely on the content.
38-
39-
### 3. 🔄 Advanced Database Synchronization
40-
Bypass the proprietary cloud and sync directly with your own infrastructure.
41-
- **Native Support**: Direct integration with **MySQL** and **PostgreSQL**.
42-
- **Vercel Proxy Bridge**: One-click deployment of a secure RBAC proxy. Your database credentials stay encrypted in Vercel environment variables—never stored on user machines.
43-
- **Real-Time Connectivity**: Instantly syncs changes across team members while maintaining an offline-first cache for zero-latency editing.
44-
- **Smart Error Recovery**: Robust handling for VPN/Firewall interruptions with detailed connection error reporting and one-click retry.
45-
46-
### 4. ⚡ High-Performance Request Engine
47-
A testing suite built for speed and precision.
48-
- **Complete Method Support**: GET, POST, PUT, DELETE, PATCH, and OPTIONS.
49-
- **Variable Injection**: Multi-environment support with dynamic variable substitution in URLs, Headers, and Bodies.
50-
- **Response Analytics**: Real-time benchmarks for execution time, payload size, and status codes.
51-
- **Rich Body Support**: JSON (with syntax highlighting), Key-Value pairs, and raw text.
52-
53-
### 5. 🎨 Aesthetic & Ergonomic UI
54-
Designed for developers who spend 8+ hours a day in their tools.
55-
- **Premium Monochrome Design**: A sleek, glassmorphic dark-mode interface that reduces eye strain.
56-
- **Dynamic Font Scaling**: Global font scaling (10px to 20px) ensures accessibility and comfort on any display density.
57-
- **Zero-Flicker Performance**: Optimized React components and IndexedDB caching for a snappy, native feel.
58-
59-
---
60-
61-
## 🛠️ Technical Architecture
62-
63-
API Documenter is engineered with a **Security-First** mindset:
64-
65-
- **Frontend**: React 18 & TypeScript for type-safe UI logic.
66-
- **Desktop Layer**: Electron with a hardened IPC bridge.
67-
- **Local Persistence**: **Dexie.js (IndexedDB)** for ultra-fast, offline-first data storage.
68-
- **Remote Bridge**: A serverless **Node.js Proxy** (deployed to Vercel) that handles DB pooling and RBAC authorization without exposing internal ports.
69-
- **State Engine**: **Zustand** for lightweight UI state and **React Query** for robust server-state synchronization.
70-
71-
---
72-
73-
## 📦 Installation & Setup
74-
75-
### For Developers
76-
77-
1. **Clone the repository:**
78-
```bash
79-
git clone https://github.com/PraneethKulukuri26/API-Documenter.git
80-
cd API-Documenter
81-
```
82-
83-
2. **Install dependencies:**
84-
```bash
85-
npm install
86-
```
87-
88-
3. **Start Development:**
89-
```bash
90-
npm run dev
91-
```
92-
93-
4. **Package for Distribution:**
94-
```bash
95-
npm run build:win # Windows
96-
npm run build:mac # macOS
97-
```
98-
99-
---
100-
101-
## 🛡️ Privacy Commitment
102-
103-
**Your data is yours.** API Documenter does not track your requests, store your passwords, or upload your documentation to external servers. All team collaboration happens through **your** database and **your** Vercel account.
104-
105-
---
106-
107-
<div align="center">
108-
Built for the community by <a href="https://github.com/PraneethKulukuri26">Praneeth Kulukuri</a>
109-
</div>
1+
<div align="center">
2+
<img src="resources/icon.jpg" alt="API Documenter Logo" width="128" />
3+
4+
# API Documenter
5+
### The Professional Self-Hosted API Ecosystem
6+
7+
**Postman Power + Enterprise Control + 100% Data Ownership.**
8+
9+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10+
[![Version](https://img.shields.io/badge/version-1.0.24-emerald.svg)](package.json)
11+
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
12+
[![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)](#)
13+
</div>
14+
15+
---
16+
17+
## 🌟 The Vision
18+
19+
**API Documenter** is more than just an API client; it is a complete **Documentation, Testing, and Collaboration Ecosystem**. It was built for engineering teams that cannot compromise on data privacy or reliability. While existing tools force your sensitive API keys and internal endpoints onto their cloud, API Documenter keeps your data exactly where it belongs: **on your machine, in your Git repository, and in your private database.**
20+
21+
---
22+
23+
## 🤝 The Developer-Friendly Philosophy (Inspired by Bruno)
24+
25+
Why do developers love tools like Bruno? Because **transparency matters**.
26+
27+
In API Documenter, there are **no opaque cloud synchronization engines** holding your data hostage. Everything you create is stored locally as plain text (`.apidoc`, `.folder`, `.json`) in a transparent, easily readable folder structure.
28+
29+
- **Pure Git Control:** Because your APIs are just files in a folder, you can use your standard Git workflows. Branch, commit, review, and merge your API specs right alongside your backend code.
30+
- **No Forced Cloud Backend:** We don't force you onto a proprietary cloud. You own your data.
31+
- **Direct File Editing:** You can open your API workspace in VS Code, modify a `.apidoc` file by hand, and the API Documenter UI instantly reflects the change.
32+
33+
**The API Documenter Advantage:** We take this developer-friendly, transparent, local-first philosophy and superpower it for Enterprise Teams by adding **Folder-Level RBAC** and **Hybrid Database Sync**. You get the transparency of local files *plus* the collaboration power of a team workspace.
34+
35+
---
36+
37+
## 🚀 Master Feature Suite
38+
39+
### 1. 📂 Folder-Level RBAC (Enterprise Security)
40+
The first self-hosted tool to offer granular, folder-level **Role Based Access Control** via a secure Proxy Server.
41+
- **Admins**: Full access. Manage project connections, global variables, and assign team permissions.
42+
- **Editors**: Can read, write, and modify endpoints within specific folders they are assigned to, but cannot delete destructive entities.
43+
- **Viewers**: Read-only access to view documentation and test endpoints without the risk of modifying team data.
44+
- **Team Isolation**: Complete isolation between projects and selective folder visibility.
45+
46+
### 2. 📝 Advanced Documentation Engine
47+
A dedicated workspace for crafting beautiful, production-ready API documentation.
48+
- **Markdown-Native**: Write documentation using standard Markdown with real-time side-by-side preview.
49+
- **Smart Components**: Insert **Smart Table of Contents**, **Page Breaks**, and dynamic code blocks.
50+
- **Built-in PDF Compilation**: Export high-fidelity A4 documentation PDFs using a built-in Chromium engine (no external Chrome dependency required).
51+
52+
### 3. 🔄 Advanced Database Synchronization & Offline Mode
53+
Bypass the proprietary cloud and sync directly with your own infrastructure.
54+
- **Native Support**: Direct integration with **MySQL** and **PostgreSQL**.
55+
- **Offline-First Queue**: Make changes offline. The app automatically queues creations, modifications, and deletions into a robust `sync_queue`.
56+
- **Smart Conflict Resolution**: When coming back online, the app seamlessly deduplicates events, auto-resolves identical deletions, and gracefully handles `update-update` and `delete-update` conflicts with a beautiful UI.
57+
- **Vercel Proxy Bridge**: One-click deployment of a secure RBAC proxy. Your database credentials stay encrypted in Vercel environment variables—never stored on user machines.
58+
59+
### 4. 🌿 Git Integration (Version Control)
60+
True version control for your API documentation.
61+
- **Local File Watcher**: Seamlessly tracks changes across `.apidoc`, `.folder`, and `.json` schema files.
62+
- **Branch Management**: Create, switch, and sync branches directly from the application.
63+
- **Commit & Discard**: Commit your API states locally or discard un-staged changes with ease.
64+
65+
### 5. ⚡ High-Performance Request Engine
66+
A testing suite built for speed and precision.
67+
- **Complete Method Support**: GET, POST, PUT, DELETE, PATCH, and OPTIONS.
68+
- **Variable Injection**: Multi-environment support with dynamic variable substitution in URLs, Headers, and Bodies. Manage **Global** vs. **Folder-level** environment scopes.
69+
- **Response Analytics**: Real-time benchmarks for execution time, payload size, and status codes.
70+
- **Rich Body Support**: JSON (with syntax highlighting), Key-Value pairs, FormData, and raw text.
71+
72+
### 6. 🎨 Aesthetic & Ergonomic UI
73+
Designed for developers who spend 8+ hours a day in their tools.
74+
- **Premium Monochrome Design**: A sleek, glassmorphic dark-mode interface that reduces eye strain.
75+
- **Dynamic Font Scaling**: Global font scaling (10px to 20px) ensures accessibility and comfort on any display density.
76+
- **Zero-Flicker Performance**: Optimized React components and IndexedDB caching for a snappy, native feel.
77+
78+
---
79+
80+
## 🛠️ Technical Architecture
81+
82+
API Documenter is engineered with a **Security-First** mindset:
83+
84+
- **Frontend**: React 18 & TypeScript for type-safe UI logic.
85+
- **Desktop Layer**: Electron with a hardened IPC bridge.
86+
- **Local Persistence**: **Dexie.js (IndexedDB)** for ultra-fast, offline-first data storage.
87+
- **Remote Bridge**: A serverless **Node.js Proxy** (deployed to Vercel) that handles DB pooling and RBAC authorization without exposing internal ports.
88+
- **State Engine**: **Zustand** for lightweight UI state and **React Query** for robust server-state synchronization.
89+
90+
> 💡 **For a deep dive into the folder structure, Git integration, and Sync Queue engine, please read our comprehensive [Developer Guide](DEVELOPER.md).**
91+
92+
---
93+
94+
## 📦 Installation & Setup
95+
96+
### For Developers
97+
98+
1. **Clone the repository:**
99+
```bash
100+
git clone https://github.com/PraneethKulukuri26/API-Documenter.git
101+
cd API-Documenter
102+
```
103+
104+
2. **Install dependencies:**
105+
```bash
106+
npm install
107+
```
108+
109+
3. **Start Development:**
110+
```bash
111+
npm run dev
112+
```
113+
114+
4. **Package for Distribution:**
115+
```bash
116+
npm run build:win # Windows
117+
npm run build:mac # macOS
118+
```
119+
120+
---
121+
122+
## 🛡️ Privacy Commitment
123+
124+
**Your data is yours.** API Documenter does not track your requests, store your passwords, or upload your documentation to external servers. All team collaboration happens through **your** database and **your** Vercel account.
125+
126+
---
127+
128+
<div align="center">
129+
Built for the community by <a href="https://github.com/PraneethKulukuri26">Praneeth Kulukuri</a>
130+
</div>

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "api-documenter",
3-
"version": "1.0.23",
3+
"version": "1.0.24",
44
"description": "Self-hosted Postman alternative with folder-level RBAC and offline-first documentation",
55
"main": "./out/main/index.js",
66
"author": "Praneeth Kulukuri",
@@ -107,4 +107,4 @@
107107
}
108108
]
109109
}
110-
}
110+
}

0 commit comments

Comments
 (0)