Kognitika

Private MVP for cognitive training, Brain ID identity, adaptive analytics, and real-time duel mechanics.

Status

Current status: MVP / technical stabilization.

The main engineering priority is production risk reduction: boot recovery, storage contracts, privacy-safe identity, API consistency, test coverage, and deploy reproducibility come before new product features.

Tracking roadmap: #10

Tech Stack

• React + Vite + TypeScript
• Tailwind CSS + Motion (motion/react)
• Express + Socket.io
• Prisma + PostgreSQL
• Vitest + Playwright
• JS analytics worker with a WASM-ready boundary for future hot paths

Requirements

• Node.js 22
• pnpm 10.22.0
• PostgreSQL 15+

The canonical package manager is pnpm. Do not use npm or yarn lockfiles.

Local Setup

Install dependencies:

pnpm install

Create a local environment file:

cp .env.example .env

Start PostgreSQL with Docker Compose:

docker compose up -d db

Run Prisma setup:

pnpm prisma generate
pnpm prisma db push

Start the full-stack dev server:

pnpm dev

Default local URL: http://localhost:3006

Environment

See .env.example for the full list. Required for normal local work:

• DATABASE_URL
• JWT_SECRET
• PORT=3006
• APP_URL=http://localhost:3006
• FRONTEND_URL=http://localhost:3006
• CORS_ORIGIN=http://localhost:3006
• CORS_ALLOW_DEV_WILDCARD=false

CORS_ORIGIN accepts a comma-separated allowlist shared by Express and Socket.io. Wildcard CORS requires CORS_ORIGIN=* plus CORS_ALLOW_DEV_WILDCARD=true and is accepted only in development/test; production without an allowlist fails closed for browser cross-origin requests and logs a startup warning.

Optional integrations include Telegram, SMTP, and legacy email channels. Public auth is Brain ID-first; legacy email features must remain explicitly gated.

Never commit real secrets, tokens, raw Brain IDs, production telemetry, or user data.

Scripts

• pnpm dev - start the Express/Vite development server
• pnpm start - start the Express server
• pnpm lint - generate Prisma client and run TypeScript checks
• pnpm test - run the Vitest suite
• pnpm validate - run the core validation suite
• pnpm build - generate Prisma client and build the frontend
• pnpm test:e2e - run Playwright E2E tests and let Playwright manage its production-style webServer
• pnpm test:e2e:attached - run Playwright against an already running local server; defaults to http://127.0.0.1:3006 and is useful on Windows/proxy environments
• pnpm clean - remove only the local dist directory through a cross-platform Node helper

Validation

Before opening or merging a production-risk change, run:

pnpm lint
pnpm test
pnpm build

For navigation or post-game flow work, run:

pnpm test:e2e

If local Playwright webServer readiness is affected by a desktop proxy, start the app separately and use the attached mode:

pnpm dev
pnpm test:e2e:attached

The attached mode sets NO_PROXY for localhost and uses BASE_URL if you need a non-default URL.

Known non-blocking local warnings currently include Recharts zero-size container warnings in jsdom and React act(...) warnings in existing dashboard tests. Treat new failures as blockers.

Runtime Contracts

• Canonical port: 3006.
• Public feedback submissions use the Prisma-backed /api/feedback route as the runtime source of truth; operator verification is documented in docs/feedback-operations.md.
• Public identity is Brain ID-first; do not expose raw Brain ID, email, token, or password hashes in UI/API responses.
• Brain ID storage/recovery boundaries are defined in docs/brain-id-identity.md.
• PWA/offline-first must remain disabled until docs/pwa-offline-strategy.md acceptance gates are met.
• Rust/WASM and 60 FPS work must pass the frame-budget gate in docs/frame-budget-benchmark.md before implementation.
• Client analytics ClickEvent uses { cellId, reactionTimeMs }.
• Direct production file patches are forbidden outside documented emergency hotfixes.

Deploy

Normal deploy flow:

local branch -> commit -> push -> PR -> merge to main -> GitHub Actions deploy

The server should update through the repository-first flow. Do not edit /opt/kognitika/* or /opt/kognitika/dist/* directly during normal work.

Production health check:

curl https://kognitika.syntog.ru/api/health

The response includes buildId, which should match the deployed commit short hash. The deploy workflow reads the internal health-check port from the server .env PORT value and falls back to 3006, so production-only port overrides do not break deploy verification.

CI

GitHub Actions run:

• TypeScript lint
• Vitest tests
• build
• Playwright E2E
• deploy to the production server on main

Docker

Build and run app + database:

docker compose up --build

The app container exposes 3006:3006; PostgreSQL exposes 5432:5432.

Issue Hygiene

Use clear title prefixes:

• [P0] production outage, active security risk, or data-loss risk
• [P1] high-priority stabilization or privacy/security hardening
• [P2] medium-priority cleanup, docs, or contract hygiene
• [P3] strategic horizon

Preferred labels:

• area:boot
• area:security
• area:privacy
• area:identity
• area:storage
• area:api
• area:infra
• area:docs

License

Private repository. License is not defined for public distribution.