Quick Start Guide

Get from zero to production in under 5 minutes. This guide walks you through setting up your first Q project.

# macOS / Linux
curl https://cli.thatisaq.com/install.sh | bash

# npm
npm install -g @thatisaq/cli

# Verify installation
q --version

q auth login
# Opens browser for OAuth authentication

# List available templates
q templates list

# Scaffold a full-stack project
q init my-project —template fullstack

# Navigate into the project
cd my-project

q dev
# ✓ Local server running at http://localhost:3000
# ✓ API gateway: http://localhost:3001
# ✓ Hot reload enabled
# ✓ Mock database seeded

# One-command deploy
q deploy —env production —auto

# Or push to your main branch
# Q automatically deploys on merge

What's Next?

Platform Architecture

An in-depth look at how Q's platform is designed to deliver reliability, performance, and scalability at any scale.

High-Level Overview

Q is built on a layered architecture that separates concerns while maintaining tight integration between components. Here's how the system is structured:

Auto-Scaling

Q's platform automatically scales resources based on demand. The scaling engine monitors CPU, memory, and request latency to make real-time adjustments.

Reliability & Availability

Q is designed for 99.99% uptime. Key reliability features include:

• Multi-region deployment — Automatic failover across 12+ regions worldwide
• Automated backups — Point-in-time recovery with 30-day retention
• Zero-downtime deployments — Blue-green and canary deployment strategies
• Health checks — Continuous monitoring with automatic restart on failure
• Circuit breakers — Automatic isolation of failing downstream services

Data Models

Q uses a type-safe, schema-driven approach to data modeling. Define your data once, and Q generates types, validation, and migrations automatically.

Defining Models

Models are defined in the schema.q file using Q's declarative syntax:

// Define a User model
model User {
  id       UUID     @default(cuid()) @id
  email    String   @unique @validate(email())
  name     String   @validate(length(1, 100))
  role     Role     @default(member)
  active   Boolean  @default(true)
  avatar   URL      ?@nullable
  bio      String   ?@nullable
  posts    Post[]   @relation("UserPosts")
  createdAt DateTime @autoCreate()
  updatedAt DateTime @autoUpdate()
}

// Enum definition
enum Role {
  admin
  member
  viewer
}

// Define a Post model
model Post {
  id       UUID     @default(cuid()) @id
  title    String
  content  String
  published Boolean  @default(false)
  author   User     @relation("UserPosts", fields: ["authorId"])
  authorId UUID
  tags     String[]
  createdAt DateTime @autoCreate()
}

Generated Types

After running q generate, Q produces type-safe models for your target languages:

export interface User {
  id: string;
  email: string;
  name: string;
  role: "admin" | "member" | "viewer";
  active: boolean;
  avatar?: string | null;
  posts: Post[];
  createdAt: Date;
  updatedAt: Date;
}

#[derive(Queryable, Serialize)]
pub struct User {
  pub id: Uuid,
  pub email: String,
  pub name: String,
  pub role: Role,
  pub active: bool,
  pub avatar: Option<String>,
  pub posts: Vec<Post>,
  pub created_at: DateTime,
  pub updated_at: DateTime,
}

from pydantic import BaseModel, EmailStr

class User(BaseModel):
    id: str
    email: EmailStr
    name: str
    role: Literal["admin", "member", "viewer"]
    active: bool = True
    avatar: Optional[str] = None
    posts: list["Post"] = []
    created_at: datetime
    updated_at: datetime

Relationships

Q supports one-to-one, one-to-many, and many-to-many relationships with automatic migration generation.

Authentication

Q provides multiple authentication strategies out of the box, from API keys to OAuth 2.0, with built-in support for common providers.

Available Methods

API Keys

API keys are the simplest way to authenticate programmatic requests. Each key is scoped to a specific workspace and can be restricted to certain permissions.

# Using API key with curl
curl -X GET https://api.thatisaq.com/v3/projects \
  -H "Authorization: Bearer qsk_live_xxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

# Using API key in JavaScript
const q = new QClient({
  apiKey: process.env.Q_API_KEY,
  project: "proj_abc123",
  environment: "production",
});

const projects = await q.projects.list();
console.log(projects);

JWT Authentication

Q issues JWT tokens upon successful authentication. These tokens should be included in the Authorization header as a Bearer token.

API Overview

Q's REST API provides full programmatic access to every feature of the platform. All endpoints follow RESTful conventions and return JSON responses.

Base URL

HTTP Methods

Response Format

All API responses are JSON. Success responses wrap data in a standard envelope:

Rate Limiting

Projects API

Manage projects, their configurations, environments, and deployments programmatically.

List Projects

Query Parameters

Example Response

Create Project

Request Body

Users API

Manage user accounts, roles, and permissions within your workspace.

List Workspace Users

Invite User

Update User Role

Analytics API

Access real-time and historical analytics data for your projects. Currently in beta.

Get Project Metrics

Query Parameters

Webhooks

Receive real-time notifications about events in your workspace. Configure webhook endpoints to receive event payloads via HTTP POST.

Event Types

Webhook Payload

{
  "id": "evt_q4x8n2m9abc",
  "type": "project.deployed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "project_id": "proj_q4x8n2m9",
    "environment": "production",
    "commit": "a3f2c8d",
    "duration_ms": 24500,
    "status": "success"
  }
}

Payload Verification

Verify webhook signatures using the X-Q-Signature header:

import { createHmac } from "crypto";

function verifyWebhook(payload, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(payload)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Error Handling

Q uses standard HTTP status codes and returns structured error responses for easy debugging.

Error Response Format

{
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "The project you're looking for doesn't exist.",
    "documentation_url": "https://docs.thatisaq.com/errors/PROJECT_NOT_FOUND",
    "request_id": "req_xxx123",
    "details": { // Optional additional context }
  }
}

HTTP Status Codes

Best Practices

• Always check response status — Never assume success. Check response.ok or the HTTP status code.
• Use request_id for support — Include the request_id when contacting support for faster resolution.
• Implement exponential backoff — For rate-limited or transient errors, retry with exponential backoff.
• Catch specific errors — Handle different error codes differently rather than using a generic catch.

try {
  const response = await q.projects.get("proj_invalid");
} catch (err) {
  switch (err.code) {
    case "PROJECT_NOT_FOUND":
      // Handle 404 — show user-friendly message
      break;
    case "RATE_LIMITED":
      // Retry with backoff
      await sleep(Math.random() * 5000);
      break;
    case "AUTH_REQUIRED":
      // Redirect to login
      break;
    default:
      // Log for debugging
      await logError(err.request_id, err.message);
  }
}

Migration Guide

Step-by-step instructions for migrating your existing projects to the Q platform. Covers V2 → V3 and third-party platform migrations.

V2 to V3 Migration

Migration Steps

# Run the automated migration tool
q migrate --from v2 --to v3

# Review the generated migration plan
q migrate --plan --output migration.md

# Apply migrations
q migrate --apply --dry-run # Preview first!

Deployment

Configure and manage deployments for your Q projects, including CI/CD integration, rollback strategies, and environment management.

Deployment Strategies

CI/CD Integration

Q integrates with all major CI/CD platforms:

• 🔷 GitHub Actions — Use @thatisaq/deploy-action
• 🔷 GitLab CI/CD — Use q deploy in your pipeline
• 🔷 Jenkins — Use the Q Pipeline Plugin
• 🔷 Vercel — Push to deploy with Q provider
• 🔷 ArgoCD — Use Q as a GitOps provider

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Q
        uses: @thatisaq/deploy-action@v3
        with:
          api-key: ${{ secrets.Q_API_KEY }}
          environment: production
          strategy: canary

Security

Learn about Q's security model, compliance certifications, and best practices for securing your applications.

Compliance

Q maintains the following compliance certifications:

• 🏅 SOC 2 Type II — Annual independent audit
• 🏅 ISO 27001 — Information security management
• 🏅 GDPR — Full data protection compliance
• 🏅 HIPAA — Healthcare data handling (Enterprise)
• 🏅 PCI DSS — Payment card industry compliance

Best Practices

1. Use Environment Variables for Secrets

# ❌ Never do this
const API_KEY = "sk_live_xxx";

# ✅ Do this instead
const API_KEY = process.env.Q_API_KEY;

2. Rotate API Keys Regularly

Rotate API keys every 90 days. Use the q keys rotate command for zero-downtime key rotation.

3. Enable Audit Logging

Enable audit logs in your workspace settings to track all admin actions and API access.

4. Use IP Allowlisting

Restrict API access to known IP ranges for additional security.

Frequently Asked Questions

Common questions and answers about the Q platform, pricing, deployment, and more.

General

Q: What is That Is A Q?

A: That Is A Q is a next-generation development platform that provides a unified suite of tools for building, deploying, and managing modern applications.

Q: Is there a free tier?

A: Yes! The Starter plan includes up to 3 projects, 10GB bandwidth, and community support — all free forever.

Q: Can I use Q with my existing tools?

A: Absolutely. Q integrates with GitHub, GitLab, VS Code, Docker, Kubernetes, Terraform, and many more tools.

Technical

Q: What languages does Q support?

A: Q supports JavaScript/TypeScript, Python, Rust, Go, and Ruby. Custom runtimes are available for Enterprise customers.

Q: How does auto-scaling work?

A: Q monitors CPU, memory, and request latency metrics. When thresholds are crossed, Q automatically provisions additional instances within seconds.

Q: Can I self-host Q?

A: Yes, Q offers an on-premises edition for Enterprise customers with full self-hosting support.

Pricing

Q: How does billing work?

A: Q uses a usage-based billing model. You're charged per compute second, bandwidth GB, and storage GB. See our pricing page for details.

Q: What happens if I exceed my plan limits?

A: Your application won't be interrupted. We'll notify you and offer to upgrade your plan. No surprise overages.

Changelog

Track updates, new features, and improvements to the Q platform.

v3.2.0 — January 2025

v3.1.0 — November 2024

v3.0.0 — September 2024

Roadmap

Our planned features and upcoming improvements to the Q platform.

Q1 2025 — Completed ✅

• ✅ Analytics API (beta)
• ✅ AI-assisted migrations
• ✅ Improved build performance

Q2 2025 — Planned

• 🔜 Edge Functions — Deploy serverless functions at the edge
• 🔜 Database migrations — Automated schema sync across environments
• 🔜 Team collaboration — Real-time collaborative editing
• 🔜 CLI improvements — New q ai assistant commands

Q3 2025 — Planned

• 🔜 Plugin marketplace — First-party and community plugins
• 🔜 Performance profiler — Real-time performance analysis
• 🔜 Multi-cloud deployment — Deploy to AWS, GCP, Azure

Q4 2025 — Planned

• 🔜 AI code review — Automated PR reviews with AI
• 🔜 Workspace templates — Community-shared project templates
• 🔜 GraphQL federation — Subgraph support for microservices

Contributing

We welcome contributions from the community. This guide will help you get started.

Getting Started

git clone git@github.com:thatisaq/q.git
cd q
npm install
q dev

git checkout -b feature/my-awesome-change

# Follow conventional commits
# feat: add new feature
# fix: fix a bug
# docs: update documentation
# refactor: restructure code
# test: add or update tests

Code of Conduct

We follow the Contributor Covenant Code of Conduct. Be respectful, inclusive, and constructive in all interactions.

Pull Request Process

• Include tests for all changes
• Update documentation as needed
• Ensure all CI checks pass
• Link any related issues
• Keep PRs focused and small