🖋️ Glyph

A lightweight, real-time collaborative LaTeX editor.

📖 Table of Contents

🌌 Project Overview
🛑 The Problem & Solution
⚡ Key Features
📐 System Architecture
📁 Directory Structure
🛠️ Tech Stack
🚀 Getting Started
🔍 Troubleshooting & FAQs
🤝 GirlScript Summer of Code (GSSOC) Contributors Guidelines
👑 Project Admins & Maintainers
📜 License

🌌 Project Overview

Glyph is an open-source, web-based collaborative LaTeX editor engineered for team productivity and speed. It provides real-time document synchronization, high-fidelity compilation inside sandboxed environment, live syntax highlighting, workspace management, and instant sharing permissions.

Whether you are writing a research paper with peers, putting together homework assignments, or designing documentation templates, Glyph offers a distraction-free space to compose and compile TeX sources directly in your browser.

🛑 The Problem & Solution

The Problem

Host Security Risks: Compiling user-submitted LaTeX documents directly on a host server is highly insecure. TeX packages can execute arbitrary system commands via \write18 or perform file reads/writes, compromising host security.
Synchronization Overhead: Collaborative LaTeX writing often relies on manual Git syncs or expensive subscription models, which degrades the rapid authoring workflow.
Clunky Setups: Setting up a complete LaTeX ecosystem locally requires downloading massive packages (~5GB for texlive-full), configuring system environment variables, and maintaining separate compilers.

The Glyph Solution

Sandboxed compilation worker: Compilations are handled by an isolated Docker container (ubuntu base + texlive-full) with restricted privileges, protecting the server.
CRDT-based Real-time collaboration: Integrated with Yjs and WebSocket protocols to enable seamless, low-latency, conflict-free editing, complete with active collaborator lists and cursor presence.
Painless setup: Glyph bundles dependencies inside Docker. It offers a hybrid compile capability—using host latexmk if installed, or falling back seamlessly to Docker compilation if not.

⚡ Key Features

Real-Time Editing & Sync: Live collaboration powered by Yjs CRDTs over WebSockets. Watch teammates make edits, select text, and move their cursors in real time.
Sandboxed Background Compilation: Compilation jobs are managed via a database-backed transaction queue (FOR UPDATE SKIP LOCKED) and processed in isolation.
Persistent File Explorer: Tree-structured workspace explorer supporting nested files and folders. The workspace structure is persisted inside PostgreSQL.
Hybrid Compilation: Smart compile flow. Automatically detects local host capabilities and defaults to Docker-based sandboxed compilation if TeX Live is missing locally.
Access Control & Shareable Links: Control permissions dynamically. Share read-only or collaborative (write-access) projects via unique Clerk-integrated tokens or invite collaborator IDs directly.
Split Screen Previewing: View output instantly side-by-side using the built-in PDF viewer or preview compiled LaTeX documents as live HTML.

📐 System Architecture

Glyph utilizes a decoupled modern architecture combining a monorepo workspace for frontend components, an API server, and a background queue worker.

graph TD
    %% User Interfacing
    Client[Next.js Client Client App]
    Editor[CodeMirror 6 / Editor]
    Client -->|WS Protocol / Cursor / Document Updates| YjsServer[Yjs WS Server Hono]
    Client -->|REST HTTP Requests| APIServer[API REST Server Hono]
    
    %% Authentication & Databases
    Clerk[Clerk Auth JWT Service] <-->|Validate Auth Tokens| APIServer
    APIServer -->|Read/Write Projects, Collaborators, Share Links| PostgreSQL[(PostgreSQL Database)]
    YjsServer -->|Persist Binary Document State as BYTEA| PostgreSQL
    
    %% Compilation Orchestration
    APIServer -->|Enqueue Compilation Job status: queued| PostgreSQL
    
    %% Sidecar worker polling
    Worker[Compile Sidecar Worker] <-->|Transaction Poll: FOR UPDATE SKIP LOCKED| PostgreSQL
    Worker -->|Write Project Source Files| TempDir[Local Workspaces: /tmp/workspaces]
    
    %% Compiling
    TempDir -->|Host Compiler| LocalTex[latexmk on Host]
    TempDir -->|Fallback Mount: /workspace| DockerContainer[Docker Sandboxed Container: glyph-compiler]
    
    LocalTex -->|Output main.pdf| Worker
    DockerContainer -->|Output main.pdf| Worker
    
    %% Save PDF back
    Worker -->|Update compilation status: success, write pdf_data BYTEA| PostgreSQL

📁 Directory Structure

Glyph/
├── .github/                 # GitHub issues, PR templates, and workflow configurations
├── docker/                  # Docker container build scripts for LaTeX compilation
│   ├── Dockerfile           # Standard Ubuntu 24.04 image + TeX Live full suite
│   └── worker.sh            # Safe bash script parsing TeX parameters & running latexmk
├── frontend/                # Next.js Frontend application (TypeScript, Tailwind CSS v4)
│   ├── src/
│   │   ├── app/             # Application pages (Landing, Dashboard, Profile, Editor)
│   │   ├── components/      # UI components (Editor, PdfViewer, ShareModal, Sidebar)
│   │   ├── lib/             # API client, compile triggers, and network helpers
│   │   └── types/           # Core typescript interfaces (Project, File, Collaborator)
│   └── public/              # Global static files and images
├── server/                  # Hono Backend REST API & WebSockets server (Node.js, TypeScript)
│   ├── src/
│   │   ├── config/          # Configurations: environment variables, DB client, Yjs sockets
│   │   ├── controllers/     # Controller handlers orchestrating database modifications
│   │   ├── routes/          # REST Endpoint declarations (Auth, Projects, Collaborators)
│   │   ├── compileWorker.ts # Queue listener sidecar polling and running LaTeX builds
│   │   └── index.ts         # Server boot script listening to API requests & WebSockets
├── scripts/                 # Utility scripts for development
│   └── dev.sh               # Pre-flight environment verifier and auto-start manager
├── docker-compose.yml       # Full-stack orchestration (DB, backend, frontend, compile-worker)
├── package.json             # Root npm workspace configuration (Monorepo setup)
└── package-lock.json        # Locked packages for monorepo consistency

🛠️ Tech Stack

Frontend

Framework: Next.js 16 (App Router) for rapid server-side hydration, path routing, and high-performance client applications.
Language: TypeScript to enforce robust type-safety across components.
Styling: Tailwind CSS v4 featuring modern utility variables, flexbox structures, and dark/light system color palettes.
Editor Engine: CodeMirror 6 for extensible syntax highlighting, lines rendering, linting, and plugin support.
State Sync: Yjs implementing conflict-free replicated data types (CRDTs) to sync editor models.

Backend

API Framework: Hono v4 (Node.js) for lightweight, fast HTTP route handling and WebSockets server gateway.
Document Synchronization: Y-Websocket server provider managing WebSocket updates, synchronizing document vectors, and writing binary states back to database.
Database Client: node-postgres (pg) using connection pooling for optimized, concurrent queries.

Infra & Services

Database: PostgreSQL storing user files, access roles, project hierarchies, and raw PDF data.
Authentication: Clerk Auth providing secure login flow, profile controls, session persistence, and organization validation.
Isolation: Docker creating a sandboxed, dependency-secure Linux environment (ubuntu base + texlive-full build tools) for compiling LaTeX source trees safely.

🚀 Getting Started

Follow the guide below to set up your local development environment.

Prerequisites

Ensure you have the following installed:

Node.js: v20.x or later.
Docker Desktop: Required for PostgreSQL, LaTeX compilation, and optional full-stack deployment. Ensure Docker is running.
Clerk Account: Free account to manage user authentication.

Note: You do not need a separate PostgreSQL installation — Docker Compose provides one automatically.

Clerk Configuration

Before running Glyph, you must register a project with Clerk:

Go to the Clerk Dashboard and create a new application.
Select Email and GitHub/Google as social providers.
Once created, copy the Publishable Key and Secret Key.
In the Clerk dashboard, set your redirect URLs:
- Sign In: http://localhost:3000/sign-in
- Sign Up: http://localhost:3000/sign-up
- After Sign In: http://localhost:3000/dashboard
- After Sign Out: http://localhost:3000/

Environment Variables Setup

Glyph uses a single .env file at the repository root to configure all services (frontend, backend, database, and compile worker).

# Copy the template
cp .env.example .env

Then open .env and fill in your keys:

# ── CLERK AUTHENTICATION ──────────────────────────────────────
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...   # From Clerk Dashboard
CLERK_PUBLISHABLE_KEY=pk_test_...               # Same as above
CLERK_SECRET_KEY=sk_test_...                    # From Clerk Dashboard

# ── GEMINI AI ASSISTANT ───────────────────────────────────────
GEMINI_API_KEY=your_gemini_api_key_here         # From Google AI Studio
GEMINI_MODEL=gemini-2.5-flash

All other values (ports, database credentials, Clerk routes) have sensible defaults — you only need to set the keys above.

Option 1: Docker Compose (Recommended)

The easiest way to start everything. One command boots PostgreSQL + Backend + Frontend + Compile Worker:

# Build all service images
docker compose build

# Start the entire stack in detached mode
docker compose up -d

Service	URL	Description
Frontend	http://localhost:3000	Next.js web application
Backend	http://localhost:8083	Hono REST API + WebSocket server
Database	`localhost:5433`	PostgreSQL (mapped to host port 5433)
Compile Worker	—	Background LaTeX compilation queue

To stop all services:

docker compose down

Option 2: Quick Start Script (Local Development)

For hot-reloading during development, use the helper script. It loads environment variables from the root .env, installs dependencies, builds the LaTeX compiler image, and starts all dev servers concurrently:

# Make the helper script executable (first time only)
chmod +x scripts/dev.sh

# Start the dev environment
./scripts/dev.sh

Note: This option requires a running PostgreSQL instance. You can start one with docker compose up db -d before running the script.

Option 3: Manual Workspace Setup

If you prefer full control over each step:

1. Install Workspace Dependencies

npm install

2. Start PostgreSQL via Docker Compose

docker compose up db -d

This starts PostgreSQL on host port 5433 with credentials from your .env file. The database schema is auto-created on backend startup.

3. Build the LaTeX Compiler Container

docker build -t glyph-compiler ./docker

4. Start All Dev Servers

npm run dev

Frontend: http://localhost:3000
Backend: http://localhost:8083

🔍 Troubleshooting & FAQs

Q1: Compilation fails immediately with "main.pdf was not produced by latexmk"

Cause: This happens if your main.tex file contains compilation errors or misses structural definitions.
Resolution: Check the "Logs" pane in the editor sidebar. It details the line numbers and LaTeX compiling errors thrown by latexmk.

Q2: Docker worker throws permission errors / fails to connect to socket (Linux/Mac)

Cause: Your user account does not have sufficient permission to access the Docker daemon socket (/var/run/docker.sock).
Resolution: Ensure Docker Desktop is running. On Linux hosts, add your user to the docker group:
```
sudo usermod -aG docker $USER
```
After updating group permissions, restart your shell or computer for changes to take effect.

Q3: Clerk triggers authentication loops or redirection errors

Cause: Missed matching Clerk environment variables in the root .env or Clerk settings.
Resolution: Verify that NEXT_PUBLIC_CLERK_SIGN_IN_URL is set to /sign-in and NEXT_PUBLIC_CLERK_SIGN_UP_URL is set to /sign-up, and match these targets inside the Clerk dashboard settings.

Q4: Database connection failed (pg Pool connection timeout)

Cause: The Hono server cannot establish connection with PostgreSQL.
Resolution: Ensure PostgreSQL is up (run docker compose up db -d). The default connection uses host port 5433. Double-check your DATABASE_URL in the root .env file.

🤝 GirlScript Summer of Code (GSSOC) Contributors Guidelines

Welcome to GSSOC '26! 🎉 We are excited to collaborate with you to build Glyph. To ensure a smooth experience, please follow these guidelines strictly:

1. Issue Assignment Workflow

Never work on unassigned issues: Pull Requests referencing issues that are not formally assigned to you by a Project Admin/Mentor will not be accepted.
Claiming an issue: Browse the Issues list, identify an open item, and comment on it stating why you would like to tackle it.
Timeout rule: Assigned issues must have progress shown within 3 days. If there are no updates or code submissions, the issue will be unassigned and reassigned to other waiting contributors.

2. Branch Naming Standard

Create a dedicated branch from the latest upstream main for every issue. Name your branch using the format below:

feature/issue-[issue-number]-[brief-description]
fix/issue-[issue-number]-[brief-description]
docs/issue-[issue-number]-[brief-description]

Example: feature/issue-42-dark-mode-toggle

3. Commit Format Conventions

We use Conventional Commits standards. This helps keep our git log clean and readable:

feat: <description>: Introducing a new feature.
fix: <description>: Fixing a bug.
docs: <description>: Writing or updating documentation (e.g. README updates).
refactor: <description>: Modifying code without adding features or fixing bugs.
style: <description>: Formatting adjustments, whitespace cleanup, or missing semi-colons.
chore: <description>: General maintenance tasks, package updates, or CLI scripts.

Example commit: git commit -m "feat: add real-time active users list component"

4. Code Quality & Formatting

Linting: Verify that all files adhere to lint configurations prior to opening a PR.

# Run in frontend folder
npm run lint
# Check types in server folder
npm run type-check:server

Clean PRs: Always create self-contained Pull Requests. One PR should solve exactly one issue. Do not bundle multiple unrelated features into a single PR.

👑 Project Admins & Maintainers

Profile	Role	Contact Channels
Anik	Project Admin & Creator

📜 License

Distributed under the Apache License 2.0. See the LICENSE file in the root directory for more details.

Show some love! ⭐

If you find Glyph helpful or plans to contribute, consider starring the repository to support our open-source growth!

Name		Name	Last commit message	Last commit date
.github		.github
.vscode		.vscode
docker		docker
frontend		frontend
scripts		scripts
server		server
.DS_Store		.DS_Store
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEPLOYMENT_RAILWAY.md		DEPLOYMENT_RAILWAY.md
DEPLOYMENT_RENDER.md		DEPLOYMENT_RENDER.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
render.yaml		render.yaml

Latest commit

History

Folders and files

Repository files navigation