Tech Stack

An overview of the technology stack used across the guinness-backend monorepo.

---

Summary

Category	Technology
Language	TypeScript
Runtime	Bun
Web framework	Hono
ORM	Drizzle ORM
Validation	Zod v4
Authentication	AWS Cognito (JWT Bearer)
Database	PostgreSQL (api-user and api-admin)
Cloud	AWS (S3, SQS, Cognito)
Logging	Winston
Testing	Vitest + Testcontainers
Lint / Format	Biome
Monorepo	Turborepo
Git hooks	Lefthook

---

Runtime and Framework

Bun

JavaScript / TypeScript runtime. Node.js-compatible with fast startup and execution. Also used as a package manager and test runner.

Hono (v4.12)

Lightweight web framework. Combined with the @hono/zod-openapi plugin to auto-generate OpenAPI specs from Zod schemas.

import { OpenAPIHono } from '@hono/zod-openapi';

const app = new OpenAPIHono();

Turborepo

Build orchestrator for the monorepo. Manages task caching and parallel execution.

---

Database

Drizzle ORM

TypeScript-first ORM used as a type-safe query builder. Schema definitions are centralized in packages/models.

import { db } from '@/lib/database';
import { users } from '@guinness-backend/models/postgresql';
import { eq } from 'drizzle-orm';

const user = await db.select().from(users).where(eq(users.id, userId)).limit(1);

Drizzle Kit

Schema migration tool. PostgreSQL migrations are managed in apps/migration-pg.

PostgreSQL

Database used by api-user and api-admin. Stores admin accounts, sessions, organizations, projects, authoritative Design and Code workflow rows, the current codebase_index control row, user-authored codebase_rule records, and user identity. Des2Code results remain in current S3 objects.

---

Validation

Zod (v4)

Schema validation library used for:

• Request body / path parameter / query parameter validation
• Environment variable validation (config/env.ts)
• OpenAPI component schema definitions

const schema = z.object({
  organization_id: z.string().uuid(),
  page: z.number().int().min(1).default(1),
});

---

Authentication

AWS Cognito

Authentication infrastructure using JWT Bearer tokens. api-user and api-admin use separate pools.

App	Pool type
api-user	App pool (end users)
api-admin	Admin pool (4D staff)

Token verification logic is centralized in packages/utils/src/cognito-jwt.ts.

---

AWS Services

Service	Purpose
Cognito	User authentication and JWT issuance
S3	Asset file storage (screenshots, etc.)
SQS	AI conversion job queuing (Des2Code, etc.)

---

Logging

Winston

Structured logging library. Configuration is centralized in packages/utils/src/logger.ts.

logger.info('Operation completed', {
  operation: 'user.findById',
  duration: 123,
  requestId: 'uuid',
});

Level	Usage
info	Successful operations
warn	Recoverable issues
error	Failures and exceptions
debug	Detailed debug information (development only)

---

Testing

Vitest

Test runner. Global setup is managed in packages/guinness-backend-sdk/src/test-utils/vitest-global-setup.ts.

Testcontainers (@testcontainers/postgresql)

Spins up real PostgreSQL containers for integration tests. Configured in packages/guinness-backend-sdk/src/test-utils/postgres-container.ts.

---

Lint / Format

Biome

Unified lint and format tool used as a replacement for ESLint + Prettier.

---

Shared Packages

Common logic is centralized in the monorepo's packages/ directory.

Package	Contents
@guinness-backend/models	Drizzle ORM PostgreSQL schemas
@guinness-backend/utils	JWT verification, error classes, pagination, logger, encryption, response formatting
@guinness-backend/guinness-backend-sdk	Testcontainers setup, Vitest global setup, shared backend helpers
@guinness-backend/typescript-config	Shared tsconfig presets

Custom Error Classes (packages/utils/src/error.ts)

ValidationError
UnauthorizedError
ForbiddenError
NotFoundError
ConflictError
InternalServerError

---

Git Hooks

Lefthook

Git hook manager. Automatically runs lint and type checks before commits.