Skip to content

README.md

Latest commit

 

History

History
221 lines (156 loc) · 9.26 KB

README.md

File metadata and controls

221 lines (156 loc) · 9.26 KB

🔗 CodeLink

CodeLink is a premium developer tool that brings AI-assisted coding to your mobile device. Review diffs, track unsaved changes, compose AI prompts, and securely inject instructions directly into your local AI code editor (Continue, Kiro, Cursor, or Antigravity) — all from your phone, without cloud dependencies or synchronizing repositories.

🏗️ Architecture Overview

CodeLink is built with a highly secure, modular, and performant monorepo architecture:

                  ┌──────────────────────────────┐
                  │      VS Code Extension       │ (TypeScript Host)
                  │  - FileWatcher & Git Diffs   │
                  │  - Editor Adapter Registry  │
                  └──────────────┬───────────────┘
                                 │
                                 │ WebSockets (JWT Auth)
                                 ▼
   ┌──────────────────────────────────────────────────────────┐
   │                  Docker Compose Backend                  │
   │                                                          │
   │   ┌─────────────────────┐      ┌─────────────────────┐   │
   │   │    Auth Service     │◀────▶│    Relay Service    │   │
   │   │       (Go REST)     │      │   (Go WebSocket)    │   │
   │   └──────────┬──────────┘      └──────────┬──────────┘   │
   │              │                            │              │
   │              ▼                            ▼              │
   │      ┌───────────────┐            ┌───────────────┐      │
   │      │  PostgreSQL   │            │  Redis Cache  │      │
   │      └───────────────┘            └───────────────┘      │
   └─────────────────────────────┬────────────────────────────┘
                                 │
                                 │ WebSockets (JWT Auth)
                                 ▼
                  ┌──────────────────────────────┐
                  │        Mobile Client         │ (React Native / Expo)
                  │  - Unified Mobile Diff View  │
                  │  - Prompt Composer Console   │
                  └──────────────────────────────┘

1. VS Code Extension (packages/vscode-extension)

A TypeScript host extension that integrates into your local workspace.

  • Git Integration: Uses a high-performance FileWatcher (debounced) and SnapshotEngine to compute differences between current file states and Git HEAD.
  • Patch Engine: Compiles patches using PatchEncoder and transmits them as SYNC_FULL_CONTEXT message envelopes.
  • Editor Adapter Registry: Detects installed AI editors (Continue, Kiro, Cursor, Antigravity) and safely injects prompts using public VS Code command APIs, with no fragile UI scraping.
  • Authentication: Generates RSA keys locally via KeyManager to securely pair with mobile devices.

2. Auth Service (services/auth)

A microservice written in Go that acts as the source of truth for identity and trust.

  • Laptop Management: Stores registered laptop identities and public keys in PostgreSQL.
  • Session Control: Manages user authentication, pairing requests, and signs secure JWTs using its private key.
  • Revocations: Coordinates session cancellations and tracks session invalidations in Redis.

3. Relay Service (services/relay)

A high-throughput WebSocket routing hub built in Go.

  • Secure Routing: Validates JWT signatures using the Auth Service's public key.
  • Real-Time Delivery: Acts as a stateful WebSocket tunnel routing prompt commands and code diffs between connected extensions and paired mobile devices.
  • PubSub Integration: Utilizes Redis for cross-node message distribution and connection tracking.

4. Mobile Client (packages/mobile)

A modern, native-feeling Expo/React Native application for iOS, Android, and web.

  • QR Pairing: Scans QR codes generated by the VS Code extension to establish secure pairing.
  • Diff Viewer: Displays unified code diffs using a mobile-optimized layout with unsaved "dirty" state indicators.
  • Prompt Composer: Features a sleek console for drafting prompt instructions and sending them directly to the active VS Code AI editor.

5. Protocol Package (packages/protocol)

A shared TypeScript library containing the core message type definitions, JSON codecs, type guards, and envelope encoders/decoders (buildEnvelope, parseEnvelope).

📂 Project Structure

codelink/
├── packages/
│   ├── protocol/          # Shared TypeScript contracts and encoders (Library)
│   ├── vscode-extension/  # VS Code Host Extension (TypeScript)
│   └── mobile/            # Expo React Native App (iOS / Android / Web)
├── services/
│   ├── auth/              # Identity and Token Issuance Service (Go)
│   └── relay/             # WebSocket Message Routing Hub (Go)
├── infra/
│   ├── docker-compose.yml # Backend dependencies and service orchestration
│   └── .env.example       # Backend environmental variables template
├── scripts/
│   ├── setup-git-hooks.sh # Helper script to install pre-commit git hooks
│   └── README.md          # Comprehensive reference of development scripts
├── tsconfig.base.json     # Base TypeScript compiler directives
├── tsconfig.json          # Solution-style TypeScript compiler targets
└── package.json           # Root workspace configuration

🚀 Local Development Setup

Get the full development environment running locally in three simple steps:

Step 1: Start Backend Infrastructure

Spin up Postgres, Redis, the Auth service, and the Relay service in Docker:

# Build and start backing services and microservices
docker compose -f infra/docker-compose.yml up --build

Backends will be available on standard local ports: Auth REST on 8081, Relay WebSocket on 8082.

Step 2: Build Protocol & Extension

In a new terminal window, build the shared package and the extension:

# Install workspace dependencies
npm install

# Compile shared protocol and typescript packages
npm run build

Step 3: Run Clients

Launch VS Code Extension Development Host

  1. Open the repository root folder in VS Code.
  2. Navigate to packages/vscode-extension/src/extension.ts.
  3. Press F5 (or go to Run and Debug -> click "Run Extension").
  4. A new "Extension Development Host" VS Code window will launch with CodeLink active.

Launch Mobile Client (Expo)

In another terminal, start the Expo development server:

cd packages/mobile
npm start

Press a to run in an Android Emulator, i to run in iOS Simulator, or w to run in your local web browser.

🧪 Testing & Validation

CodeLink incorporates standard NPM workspace commands and native Go unit tests:

TypeScript Workspace Quality Tools

# Compile and build typescript packages
npm run build

# Run TypeScript linter
npm run lint

# Auto-fix linter issues
npm run lint:fix

# Check formatting via Prettier
npm run format:check

# Format files matching styling policies
npm run format

# Run TS typechecks across workspaces
npm run typecheck

# Run Vitest unit tests
npm run test

Go Service Quality Tools

# Run unit tests across auth and relay microservices
npm run test:go

# Run verbose Go tests
npm run test:go:verbose

Git Pre-Commit Hook Integration

Prevent invalid changes from entering git by installing the pre-commit sanity checks hook:

# Make the helper script executable and execute it
chmod +x scripts/setup-git-hooks.sh
./scripts/setup-git-hooks.sh

This installs a hook that automatically executes npm run precommit before every commit, keeping your repository history clean.

🚢 Production Deployment

For production deployments, the modular microservices can be scaled independently:

  • Database & Cache: Deploy highly available managed PostgreSQL and Redis clusters.
  • Go Services: Run inside Kubernetes or container platforms behind a secure load balancer (ensure WebSocket-sticky sessions on Relay Ingress).
  • Secrets Management: Securely provide the AUTH_HMAC_SECRET, JWT Private Key PEM, and database connection strings using a dedicated secrets manager.
  • Mobile Assets: Build native Android/iOS bundles via EAS CLI (expo build), or compile PWA static assets to host on CDN networks.

📄 License

CodeLink is open-source software licensed under the MIT License.