TurboMe

A powerful markdown-based workspace and knowledge management system with Git integration.

✨ Features

• 📝 Markdown-First: Organize your documents using markdown files with frontmatter metadata
• 🗂️ Smart Workspaces: Automatically organize files into workspaces based on frontmatter
• 🔄 Git Integration: Full version control support with commit history and diff viewing
• 🎨 Rich Editor: Built-in Milkdown editor with live preview
• 🚀 Fast Search: Powerful file search using ripgrep
• 🔧 RESTful API: Comprehensive V1 API for all operations
• 💾 Local Storage: Settings stored locally for better performance

📦 Installation

npm install -g turbome

🚀 Quick Start

Start the server

turbome start
# or simply
turbome

The server will start on port 7788 by default. Open your browser and navigate to:

• Frontend: http://localhost:7788
• API Documentation: http://localhost:7788/api-docs

Command Line Options

turbome --help        # Show help
turbome --version     # Show version
turbome start         # Start the server (default)

Environment Variables

PORT=8080 turbome     # Use custom port (default: 7788)
STORAGE_DIR=/path/to/files turbome  # Set storage directory

📚 Usage

Creating Files

1. Navigate to the Explore page
2. Click "New Item" in any workspace
3. Files are automatically created with timestamps as filenames

Managing Workspaces

Workspaces are automatically created based on the workspace field in markdown frontmatter:

---
workspace: my-project
title: My Document
---

# Content here

Transferring Files

Files can be transferred between workspaces using the transfer button:

1. Click the transfer icon next to any file
2. Select target workspace or create a new one
3. File's frontmatter is automatically updated

Archiving Files

Archive files by removing them from workspaces:

1. Click the archive button on any file
2. The file's workspace frontmatter is removed
3. File remains in the filesystem but not shown in workspaces

🛠️ API

TurboMe provides a comprehensive RESTful API:

V1 Endpoints

• GET /api/v1/workspaces - List all workspaces
• GET /api/v1/files/markdown - Get markdown files
• PUT /api/v1/files/markdown - Save markdown files
• PUT /api/v1/files/markdown/frontmatter - Update frontmatter
• DELETE /api/v1/files/markdown/frontmatter - Delete frontmatter fields

Example

// Get all workspaces
fetch('http://localhost:7788/api/v1/workspaces')
  .then(res => res.json())
  .then(data => console.log(data));

🏗️ Development

Prerequisites

• Node.js >= 18
• npm >= 9

Local Development

# Clone the repository
git clone https://github.com/gitbase-ai/turbome.ai.git
cd turbome.ai

# Install dependencies
npm install

# Start development servers
npm run dev

This starts:

• Frontend dev server on http://localhost:3000
• Backend dev server on http://localhost:7788

Building

npm run build:dist

Testing

npm test

🏗️ Architecture

Frontend (client/)

• Framework: Next.js 15 with TypeScript
• Styling: Tailwind CSS 4
• Features: App Router, Turbopack, ESLint

Backend (server/)

• Framework: NestJS with TypeScript
• Features: REST API, CORS enabled, modular architecture
• Port: 3001

Shared (shared/)

• Types: Common interfaces and types
• DTOs: Data Transfer Objects with validation
• Constants: API endpoints, HTTP status codes, etc.

Key Features

• 🎯 Type Safety: End-to-end TypeScript with shared types
• 🚀 Fast Development: Hot reloading for both frontend and backend
• 📦 Monorepo: Efficient dependency management with npm workspaces
• 🔄 Code Sharing: Common types and utilities across applications
• 🎨 Modern Stack: Latest versions of Next.js and NestJS
• 🌐 No CORS Issues: Frontend proxies API requests to backend

API Endpoints

Backend serves all endpoints under /api prefix:

General

• GET /api - Welcome message
• GET /api/health - Health check

Users

• GET /api/users - Get all users
• POST /api/users - Create user
• GET /api/users/:id - Get user by ID
• PUT /api/users/:id - Update user
• DELETE /api/users/:id - Delete user

Files

• GET /api/files?file_paths=["file.txt"] - Get files content (always returns list format)
• GET /api/files?file_paths=["a.txt","b.txt"] - Get multiple files content
• GET /api/files?file_paths=["file.txt"]&metadata_only=true - Get file metadata only
• PUT /api/files?file_path=path - Create or update file
• DELETE /api/files?file_path=path - Delete file

File paths examples:

• Single file: ?file_paths=["test.txt"] → Returns { files: [...], total_count: 1, success_count: 1, error_count: 0 }
• Multiple files: ?file_paths=["file1.txt","folder/file2.txt"] → Returns list format with all files
• With encoding: ?file_paths=["file.txt"]&encoding=base64
• Metadata only: ?file_paths=["file.txt"]&metadata_only=true

Response format:

{
  "success": true,
  "data": {
    "files": [{ "file_name": "test.txt", "content": "...", ... }],
    "total_count": 1,
    "success_count": 1, 
    "error_count": 0,
    "errors": []
  }
}

Note:

• Backend serves at: http://localhost:3001/api/*
• Frontend proxies /api/* to http://localhost:3001/api/*

API Documentation

Interactive Swagger documentation is available when running the server:

Development Environment

http://localhost:3001/api/docs

Production/CLI Environment

http://localhost:7788/api/docs

The Swagger UI provides:

• Complete API endpoint documentation
• Request/response schemas
• Interactive testing interface
• Authentication support (if configured)

📝 Configuration

Settings are stored in browser localStorage:

• Draft Path: Default location for new files (default: ./drafts)

Access settings at: http://localhost:7788/settings/explore

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License.

🐛 Issues

Found a bug or have a suggestion? Please open an issue at GitHub Issues.

🙏 Acknowledgments

• Built with Next.js
• Backend powered by NestJS
• Editor powered by Milkdown
• Search powered by ripgrep

---

Made with ❤️ by TurboMe Contributors

Development vs Production

Development Mode

• Frontend: Next.js dev server on port 3000
• Backend: NestJS dev server on port 3001
• Frontend proxies /api/* to backend

npm run dev

Production Mode

• Single NestJS server serves everything on port 7788
• Static frontend files are served by NestJS
• API endpoints available at /api/*

npm run build:dist
./cli/index.js

Publishing to NPM

1. Build the package:

   npm run build:dist

2. Check the build:

   ./scripts/publish.sh

3. Publish to npm:

   npm publish

Environment Variables

Development

Create .env.local files as needed:

Client (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:3001

Server (.env)

PORT=3001
CLIENT_URL=http://localhost:3000

Production (CLI)

PORT=7788          # Server port (default: 7788)
NODE_ENV=production # Automatically set by CLI

Shared Types & API Client

The project includes shared TypeScript types and a ready-to-use API client for type-safe frontend-backend communication.

Usage in Frontend

import { FilesApiClient, GetFilesResponse } from '@shared/index';

// Create API client
const filesApi = new FilesApiClient('/api');

// Type-safe API calls
const response: GetFilesResponse = await filesApi.getFile('test.txt');
const multipleFiles = await filesApi.getFiles({
  file_paths: ['file1.txt', 'file2.txt'],
  encoding: 'text'
});

// Save file with full type safety
await filesApi.saveFile({
  file_path: 'new-file.txt',
  content: 'Hello World',
  commit_message: 'Create new file'
});

Shared Types Include

• Request/Response Types: GetFilesRequest, SaveFileRequest, etc.
• Data Models: FileInfo, MultipleFilesResponse, etc.
• API Client: FilesApiClient with all methods
• Common Types: ApiResponse, User, etc.

Benefits

• ✅ Type Safety: IntelliSense and compile-time checks
• ✅ Consistency: Same types across frontend and backend
• ✅ DX: Better developer experience with autocomplete
• ✅ Maintainability: Single source of truth for API contracts

File Storage

Development Environment

• Required: Must set STORAGE_DIR environment variable
• Example: STORAGE_DIR=/path/to/files npm run dev
• Error: Server will fail to start without STORAGE_DIR in development

Production/CLI Environment

• Default: Current working directory where CLI is executed
• Example:

  # Files stored in current directory
  turbome