# 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](https://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

```bash
pnpm install
```

### Development

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

### Build

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

### Testing

```bash
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

```env
# 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