HashHive AI Coding Instructions#

HashHive is a TypeScript reimplementation of CipherSwarm, a distributed password cracking management system orchestrating hashcat across multiple agents.

Architecture Overview#

Monorepo with Bun workspaces + Turborepo:

• packages/backend/ - Bun + Hono API with Drizzle ORM
• packages/frontend/ - React 19 + Vite SPA with shadcn/ui, TanStack Query
• packages/shared/ - Drizzle schema, Zod schemas, inferred TypeScript types
• packages/openapi/ - Agent API OpenAPI specification

Schema flow (single source of truth): Drizzle tables → drizzle-zod → Zod schemas → z.infer types. One direction, no duplication.

Route handlers call Drizzle directly — service layers only when handlers become complex.

Key services (see .kiro/specs/mern-migration/design.md):

• AuthService - Login/logout, JWT/session management
• AgentService - Registration, heartbeat, capability detection
• CampaignService - Campaign lifecycle, DAG validation, attack configuration
• TaskDistributionService - Keyspace partitioning, task generation, assignment
• ResourceService - File uploads to the S3-compatible object store (SeaweedFS in dev / air-gapped prod), hash list parsing coordination
• HashAnalysisService - Hash-type identification, hashcat mode mapping
• EventService - WebSocket broadcasting for real-time dashboard updates

Critical Design Documents#

Always consult before major changes:

• .kiro/steering/ - Product overview, tech stack, structure (source of truth)
• .kiro/specs/mern-migration/ - Requirements, detailed design, task breakdown
• AGENTS.md - AI agent guidance (extended context)
• packages/openapi/agent-api.yaml - Agent API contract (single source of truth)

Development Workflow#

Before committing any changes, always run just ci-check and ensure all checks and tests pass.

# Quick start
bun install # Install all workspace deps
docker compose up -d # Start PostgreSQL, Redis, SeaweedFS
bun dev # Start backend + frontend

# Or use just commands
just setup # Complete first-time setup
just dev # Start all services
just test # Run all tests
just lint # Lint all code
just ci-check # Full CI: lint + format + type-check + build + test

# Individual packages
bun --filter backend dev # Backend only
bun --filter frontend dev # Frontend only
bun --filter backend test # Backend tests

Configuration & Environment#

• Centralized config: packages/backend/src/config/env.ts with Zod validation
• Environment files: packages/backend/.env (copy from .env.example)
• 12-factor principles: All config via env vars, fails fast on validation errors
• Strict TypeScript: Maximum strictness via tsconfig.base.json

Code Patterns#

Formatting & Linting#

• oxlint + oxfmt for linting and formatting (not ESLint, not Prettier, not Biome); taplo for TOML
• Run just format or bun run format to format all files
• pre-commit hooks run oxfmt + taplo format checks, oxlint, and type checking

Error Handling#

• Use HTTPException from hono/http-exception for HTTP errors
• The app.onError() handler must check instanceof HTTPException before generic 500
• Structured error responses with machine-readable codes

Validation#

• Zod schemas for request/response validation (via @hono/zod-validator)
• Schema flow: Drizzle → drizzle-zod → Zod → TypeScript types
• Define schemas in packages/shared/ for cross-package reuse

Testing Strategy#

• bun for all tests (not Jest, not Vitest)
• Backend: Integration tests with test database and mocked services
• Frontend: Testing Library for components, Playwright for E2E
• Coverage target: 80%+ for critical paths

API Design#

• Agent API (/api/v1/agent/*): Pre-shared token auth, defined by OpenAPI spec
• Dashboard API (/api/v1/dashboard/*): JWT + HttpOnly cookie auth, standard CRUD
• Versioning: x-agent-api-version header for Agent API

Database (PostgreSQL + Drizzle ORM)#

• Tables: snake_case (e.g., hash_lists, project_users)
• Schema: Defined in packages/shared/src/db/schema.ts
• Migrations: Generated by drizzle-kit (just db-generate, just db-migrate)
• No destructive updates: Use explicit status fields, preserve audit trails
• Indexes: Add for common query patterns

Infrastructure Dependencies#

# docker-compose.yml provides:
PostgreSQL: localhost:5432 # Primary datastore
Redis: localhost:6379 # BullMQ queues + caching
SeaweedFS: localhost:9000 (S3), 9333 (master) # S3-compatible object storage (minioadmin/minioadmin)

Naming Conventions#

• Files: kebab-case.ts
• Components: PascalCase.tsx
• Functions: camelCase
• Types/Interfaces: PascalCase
• Constants: UPPER_SNAKE_CASE
• Database tables: snake_case

Common Pitfalls#

• exactOptionalPropertyTypes: Use spread ...(val ? {k: val} : {}) not k: val ?? undefined
• noUncheckedIndexedAccess: All arr[i] returns T | undefined — guard with null check
• noPropertyAccessFromIndexSignature: Use obj['key'] bracket notation for index signatures
• Bracket notation for index signatures: obj['key'] not obj.key under noPropertyAccessFromIndexSignature — oxlint's typescript/no-unnecessary-type-assertion should not be silenced for these accesses
• Don't skip Zod validation — validate all external input
• Don't commit secrets — use .env files (gitignored)
• Agent API changes require OpenAPI spec updates — keep contract in sync
• Read .kiro/specs/mern-migration/design.md before implementing services

Type Safety#

• Shared types in packages/shared/src/types/ for backend/frontend consistency
• Drizzle schema exports select/insert types via drizzle-zod
• OpenAPI spec defines Agent API contract types
• Zod schemas provide runtime validation + static types

Design Context#

Design context for the React frontend lives in .impeccable.md at the repo root. Read it before any UI/UX work. Summary:

Users#

HashHive serves three operator roles (admins, power-users, end users), all technical security/red-team personnel running the platform in a private lab on a closed network. 1–3 concurrent dashboard users, long sessions, often viewed on a second monitor or wall display while hashcat is running on 7–10+ GPU rigs. The job is "tell me at a glance that my rigs are running and surface the moment a hash cracks."

Brand Personality#

Operator-grade, editorial, candid. Direct technical voice ("Queue depth 12,340 exceeds warn threshold 10,000" beats "Something's not quite right!"). Treats the user as a peer, never condescends. The dashboard reads like a well-designed data magazine, not a SaaS template. Emotional register: dramatic ops theater — pit-wall HUD / NOC display, big numbers when earned, motion when the system moves, never when chrome moves.

Aesthetic Direction#

Dark-only Catppuccin Macchiato (locked via <html class="dark"> and color-scheme: dark; no light mode exists). Peach #f5a97f is the brand primary. The full Catppuccin accent range is available for editorial use — per-attack-mode chunking, graph series in lavender → sapphire → sky → teal → green sequence, domain accents — not just status. Status colors (green/yellow/red) stay reserved for actual status. Typography: Space Grotesk + Space Mono. Motion: compositor-friendly, ease-out-exponential, reserved for operator moments.

Anti-References (explicit rejection list)#

The following aesthetic lanes are rejected:

• NOT generic SaaS dashboard (no Linear/Vercel/Stripe reflex, no gradient hero metrics, no cards-on-cards)
• NOT enterprise security tool (no navy + gold, no Splunk/Tenable density)
• NOT hacker theater (no Matrix green-on-black, no skull icons, no fake-leet typography)
• NOT neon crypto dashboard (no glassmorphism, no neon gradients, no Coinbase Pro vibe)

If a design choice could be guessed from "password-cracking platform" alone, rework it.

Design Principles#

1. Theater earns its place. Motion is reserved for operator moments (crack, transition, completion), never for chrome.
2. Editorial color, never neon noise. Catppuccin's full range is for chunking and series; semantic green/yellow/red is reserved for status.
3. Every signal pairs with a non-color cue. Status = color + icon + label. Survives color-blind operators and grayscale screenshots.
4. Keyboard is a first-class peer of mouse. Visible focus rings, logical tab order, kbd hints on frequent actions, reduced-motion respected.
5. No category reflexes. SaaS-cream, enterprise-navy, hacker-green, crypto-neon are all explicit anti-references.

Conformance target: WCAG 2.2 AA (4.5:1 body text, 3:1 large text / UI boundaries). When a Catppuccin accent can't clear the text floor, pair it with weight/size/a non-color cue rather than dropping below AA. AAA is not a goal on this mid-tone palette.

For full context, principles, and locked tokens, read .impeccable.md.

Mermaid Diagrams#

When the user asks to create, edit, or visualize a diagram, follow the
instructions in .github/instructions/mermaid.instructions.md.