gadget/gadget-code/README.md

Gadget Code

A modern self-hosted and open source Agentic Engineering Environment. Gadget Code is a hackable TypeScript/Node.js web application - and application development framework - built with Express, React, Vite, and Tailwind CSS.

Gadget Code is a Gab-first initiative. It is most well-tested and tuned for use with Gab.ai as your "Big Brain" compute provider. However, it is designed to be easily adaptable for use with other compute providers as well as your own local Ollama, vLLM, or other OpenAI or Ollama API-compatible setup.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Vite Dev Server (HTTPS)                  │
│                    https://code-dev.g4dge7.com:5174         │
│                                                             │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐                │
│  │   /auth   │  │   /api    │  │  static   │                │
│  │   proxy   │  │  proxy    │  │  files    │                │
│  └────┬──────┘  └────┬──────┘  └───────────┘                │
│       │              │                                      │
│       ▼              ▼                                      │
│  ┌─────────────────────────────┐                            │
│  │   Backend (HTTP)            │                            │
│  │   http://localhost:3443     │                            │
│  │   - Express API             │                            │
│  │   - Socket.io               │                            │
│  │   - Session (Redis)         │                            │
│  │   - MongoDB                 │                            │
│  └─────────────────────────────┘                            │
└─────────────────────────────────────────────────────────────┘

Tech Stack

• Frontend: React 19, Vite 8, Tailwind CSS 4, Socket.io Client
• Backend: Express 5, TypeScript, Socket.io Server
• Database: MongoDB (Mongoose)
• Cache/Session: Redis (ioredis + connect-redis)
• File Storage: MinIO
• Testing: Vitest, Playwright

Getting Started

Prerequisites

• Node.js 22+
• pnpm 10+
• MongoDB running on localhost:27017
• Redis running on localhost:6379
• SSL certificates in ssl/ directory

Installation

pnpm install

Development

# Start both backend and frontend
pnpm dev:backend   # Backend on http://localhost:3443
pnpm dev:frontend # Frontend on https://localhost:5174

Build

pnpm build          # Build backend + frontend
pnpm build:backend # Build TypeScript only
pnpm build:frontend # Build React/Vite only

Testing

pnpm test            # Run vitest unit tests
npx playwright test  # Run E2E integration tests

Scripts

Your environment can be managed with the following package.json scripts and npx commands.

Command	Description
pnpm build	Build backend + frontend
pnpm test	Run vitest unit tests
npx playwright test	Run E2E tests
pnpm dev:backend	Start backend (port 3443)
pnpm dev:frontend	Start frontend (port 5174)
pnpm start	Start production build

Environment Variables

# Required
DTP_USER_PASSWORD_SALT="your-password-salt"
DTP_JWT_SECRET="your-jwt-secret"
DTP_SESSION_SECRET="your-session-secret"

# MongoDB
DTP_MONGODB_HOST="localhost"
DTP_MONGODB_DATABASE="gadget-code"

# Redis
DTP_REDIS_HOST="localhost"
DTP_REDIS_PORT="6379"

# HTTPS
DTP_HTTPS="enabled"
DTP_HTTPS_HOST="localhost"
DTP_HTTPS_PORT="3443"
DTP_HTTPS_KEY_FILE="/path/to/ssl/key.pem"
DTP_HTTPS_CRT_FILE="/path/to/ssl/cert.pem"

 # Session
 DTP_SESSION_TRUST_PROXY="enabled"
 DTP_SESSION_COOKIE_SECURE="enabled"
 DTP_SESSION_COOKIE_SAMESITE="strict"

Features

• User authentication (sign in, sign out)
• JWT-based session management
• RESTful API structure
• Socket.io real-time communication
• File upload support (MinIO)
• Email notifications
• Tailwind CSS frontend with dark theme

Project Structure

/src
  /config          # Environment configuration
  /controllers    # Express route handlers
  /lib            # Core utilities
  /models         # Mongoose models
  /services       # Business logic
/frontend
  /src
    /components  # React components
    /pages       # React pages
    /lib         # Frontend utilities
  /public        # Static assets
  vite.config.ts # Vite configuration
/tests
  /e2e           # Playwright tests

API Endpoints

Method	Endpoint	Description
POST	/auth/sign-in	Authenticate
GET	/auth/sign-out	Sign out
GET	/api/v1/user	Get current user

License

SEE LICENSE IN LICENSE