a.s.i.z

Self-Hosted AI Chat Platform with Multi-Provider Support

A modern, self-hosted alternative to ChatGPT with support for multiple AI providers, local models, and enterprise features.

Overview

a.s.i.z is a self-hosted, OpenAI-compatible AI chat platform that gives you complete control over your AI interactions. Built with a modern tech stack, it supports DeepSeek and local model servers, and includes enterprise features like user management, projects, conversations, and RAG capabilities.

Key Features

• DeepSeek Integration: Connect to DeepSeek AI models
• Local Model Support: Run models locally with included Phi-3 Mini server or connect to Ollama
• Real-Time Streaming: Token-by-token streaming with Server-Sent Events (SSE)
• Enterprise Auth: Complete user authentication with sessions, password reset, and security features
• Project Management: Organize conversations into projects with role-based access control
• Secure Credentials: Encrypted storage for API keys and provider credentials
• Model Registry: Centralized model management with provider abstraction
• RAG Ready: Infrastructure for Retrieval-Augmented Generation (placeholder for future implementation)
• OpenAPI Documentation: Auto-generated Swagger/OpenAPI docs at /docs
• Modern UI: Beautiful, responsive interface built with Next.js App Router and Tailwind CSS

How It Works

The platform consists of three main components working together:

1. Express REST API (api/) - Handles all backend logic, authentication, and OpenAI-compatible endpoints
2. Next.js Frontend (web/) - Provides the user interface with real-time token streaming
3. Model Servers (model-servers/) - Optional local model servers (FastAPI) for self-hosted inference

sequenceDiagram
    participant User
    participant Web as Next.js Frontend
    participant API as Express API
    participant DB as MySQL (Prisma)
    participant Provider as AI Provider
    participant Local as Local Model Server

    User->>Web: Start conversation
    Web->>API: POST /v1/chat/completions
    API->>DB: Validate session & fetch model
    API->>DB: Check user credentials
    alt DeepSeek Provider
        API->>Provider: Forward request (DeepSeek)
        Provider-->>API: Stream tokens
    else Local Model
        API->>Local: POST /v1/chat/completions
        Local-->>API: Stream tokens
    end
    API-->>Web: SSE stream tokens
    Web-->>User: Display response
    API->>DB: Save conversation & messages

Loading

Architecture

Directory Structure

.
├── api/                    # Express REST API
│   ├── src/
│   │   ├── features/      # Feature-based modules (auth, chat, models, etc.)
│   │   ├── core/          # Core utilities (auth, db, http, vector)
│   │   ├── libs/          # Adapters (inference, storage)
│   │   └── config/          # Configuration (env, logger, swagger)
│   ├── prisma/            # Database schema & migrations
│   └── tests/             # E2E and unit tests
├── web/                    # Next.js App Router frontend
│   ├── app/               # App Router pages
│   ├── components/        # React components
│   ├── features/          # Feature modules (chat, auth, models)
│   └── lib/               # Utilities (fetcher, SSE, auth)
└── model-servers/         # Local model servers
    └── phi3-mini-4k-instruct/  # Phi-3 Mini FastAPI server

Technology Stack

Backend:

• Express.js with TypeScript
• Prisma ORM with MySQL
• Pino for structured logging
• Zod for environment validation
• Swagger/OpenAPI for API documentation

Frontend:

• Next.js 15 (App Router)
• React 19
• Zustand for state management
• Tailwind CSS 4
• Server-Sent Events for streaming

Infrastructure:

• MySQL database
• FastAPI for local model servers

Supported Providers

The platform currently supports:

• DeepSeek - DeepSeek AI models
• Local Models - Run models locally via:
  • Phi-3 Mini (included FastAPI server)
  • Ollama (local inference)
  • Generic HTTP endpoints

Getting Started

Prerequisites

• Node.js 18+ and npm 7+ (for workspace support)
• MySQL 8.0+
• Python 3.8+ (for local model servers, optional)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd a.s.i.z

2. Install dependencies:

   npm install

3. Set up environment variables:

   Create api/.env based on api/.env.example:

   DATABASE_URL="mysql://user:password@localhost:3306/asiz"
   API_KEY="your-secret-api-key"
   JWT_SECRET="your-jwt-secret"
   INFERENCE_BASE_URL="http://localhost:8000"  # Optional: for local models

   Create web/.env.local based on web/.env.local.example:

   NEXT_PUBLIC_API_URL="http://localhost:3001"

4. Set up the database:

   cd api
   npx prisma migrate deploy
   npx prisma generate

5. Seed initial data (optional):

   npm run seed-models

6. Start local model server (optional):

   cd model-servers/phi3-mini-4k-instruct
   chmod +x start.sh
   ./start.sh

   See model-servers/phi3-mini-4k-instruct/README.md for details.

7. Start the application:

   # From root directory
   npm run dev

   This starts:

   • API server on http://localhost:3001
   • Web app on http://localhost:3000
   • API docs at http://localhost:3001/docs

Usage

Creating a User

Use the provided script to create your first user:

cd api
npm run create-user

Adding Provider Credentials

1. Log in to the web interface
2. Navigate to Settings → Models
3. Add your API keys for desired providers
4. Credentials are encrypted and stored securely

Starting a Conversation

1. Go to the chat interface
2. Select a model from the registry
3. Start chatting! Responses stream in real-time

Managing Projects

• Create projects to organize conversations
• Invite team members with role-based permissions
• Archive conversations when done

Features Deep Dive

Authentication & Security

• Session-based auth with secure token hashing
• Password reset flow with email tokens
• Rate limiting on authentication endpoints
• Brute force protection with login attempt tracking
• Audit logging for security events
• API key authentication for programmatic access

Chat & Conversations

• Real-time streaming with Server-Sent Events
• Conversation history with full message context
• System prompts per conversation
• Model selection from registry
• Token counting and usage tracking
• Conversation archiving and search

Model Management

• Centralized registry of available models
• Provider abstraction - switch providers without code changes
• User-specific credentials with encryption
• Local model support via FastAPI servers
• Model metadata and tagging

File Management

• File upload infrastructure (ready for implementation)
• Vector store integration (placeholder)
• Document processing pipeline

RAG (Retrieval-Augmented Generation)

• Infrastructure in place for RAG queries
• Vector store abstraction layer
• Ready for document indexing and retrieval

Development

Project Structure

The codebase follows a feature-based architecture:

API (api/src/):

• features/ - Feature modules (auth, chat, models, etc.)
• core/ - Shared utilities (auth middleware, DB client, HTTP errors)
• libs/ - External service adapters
• config/ - Configuration and environment validation

Web (web/):

• app/ - Next.js App Router pages
• components/ - Reusable React components
• features/ - Feature-specific modules
• lib/ - Utilities (API client, SSE, auth helpers)

Available Scripts

Root workspace:

• npm run dev - Start API and Web in development mode
• npm run build - Build both API and Web
• npm run lint - Lint all packages
• npm run typecheck - TypeScript type checking
• npm run test - Run all test suites

API (api/):

• npm run dev - Start with nodemon
• npm run build - Compile TypeScript
• npm run start - Run production build
• npm run test - Run Vitest suite
• npm run create-user - Create a new user
• npm run seed-models - Seed model registry

Web (web/):

• npm run dev - Start Next.js dev server
• npm run build - Build for production
• npm run start - Start production server
• npm run e2e - Run Playwright E2E tests

Testing

The project includes comprehensive testing:

• Unit tests with Vitest
• E2E tests with Playwright
• API tests with Supertest
• Coverage reports available

Run tests:

npm run test

Code Quality

• ESLint for linting
• Prettier for formatting
• TypeScript strict mode
• Prisma for type-safe database access

API Documentation

Interactive API documentation is available at /docs when the API server is running. The documentation includes:

• All endpoints with request/response schemas
• Authentication requirements
• Example requests and responses
• OpenAPI 3.0 specification

Access it at: http://localhost:3001/docs

Security Features

• Encrypted credentials - API keys stored with encryption
• Session management - Secure token-based sessions
• Rate limiting - Protection against abuse
• Input validation - Zod schemas for all inputs
• SQL injection protection - Prisma ORM
• XSS protection - React's built-in escaping
• CORS configuration - Configurable CORS policies

Environment Variables

API (api/.env)

# Database
DATABASE_URL="mysql://user:password@localhost:3306/asiz"

# Security
API_KEY="your-secret-api-key"
JWT_SECRET="your-jwt-secret"

# Server
PORT=3001
NODE_ENV="development"

# Inference
INFERENCE_BASE_URL="http://localhost:8000"  # Optional

# Email (for password reset)
SMTP_HOST="smtp.example.com"
SMTP_PORT=587
SMTP_USER="user@example.com"
SMTP_PASS="password"
SMTP_FROM="noreply@example.com"

Web (web/.env.local)

NEXT_PUBLIC_API_URL="http://localhost:3001"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

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. See LICENSE for details.

Roadmap

• Complete RAG implementation with vector store
• File upload and document processing
• Enhanced local model support (llama.cpp, vLLM)
• CI/CD pipeline with GitHub Actions
• Multi-language support
• Advanced analytics and usage tracking
• Webhook support for integrations
• Plugin system for extensibility

Acknowledgments

• Built with Next.js
• Powered by Express
• Database managed with Prisma
• Styled with Tailwind CSS

---

a.s.i.z — Your self-hosted AI chat platform.