0be354a920
Single-commit clean baseline after security scrub of niche-tells, project codenames, internal jargon, and contributor-email leaks. Contents: - 100 Rust crates (_primitives/_rust/) - 37 agent manifests (_manifests/) + generated specs (_generated/) - 67 user-invocable skills (skills/) - 33 hooks (hooks/) - Composition blocks (_blocks/) - Documentation (docs/, README.md) - TS adapter packages (_ts_packages/) - Assembler (_assembler/) - Roles (_roles/) - Templates (_templates/) - Forgejo CI (.forgejo/) Author: Denis Parfionovich <info@greendragon.info> License: see LICENSE.
208 lines
8 KiB
Markdown
208 lines
8 KiB
Markdown
# Stack Compatibility Matrix
|
|
|
|
## Verified Stack Combinations
|
|
|
|
### Fullstack TypeScript (Primary Stack — Denis/KeiSei)
|
|
```
|
|
Frontend: Next.js 14+ (App Router) + React 18+ + Zustand + Tailwind CSS
|
|
Backend: NestJS 10+ + Prisma ORM + PostgreSQL + Redis
|
|
Queue: BullMQ + Redis
|
|
Bot: Grammy (Telegram)
|
|
Storage: MinIO (S3-compatible)
|
|
Auth: NextAuth 5 / Passport.js
|
|
Search: pgvector (vector similarity)
|
|
Deploy: Docker Compose + nginx reverse proxy + certbot SSL
|
|
```
|
|
|
|
### AI/ML Stack
|
|
```
|
|
API: OpenAI SDK + Anthropic SDK + Google Generative AI
|
|
Embeddings: text-embedding-3-small (OpenAI) / pgvector storage
|
|
RAG: Custom chunking + embeddings + vector search
|
|
Images: Gemini nano-banana-pro / imagen-4.0-ultra
|
|
Video: Veo 3.1 / Kling 3.0 via Fal.ai
|
|
Batch: Anthropic Batch API (max_tokens=8192, batch_size=25)
|
|
```
|
|
|
|
### Game Dev Stack
|
|
```
|
|
Engine: Phaser 3.90 + TypeScript + Vite
|
|
Emulation: Nostalgist.js (snes9x core)
|
|
Assets: DALL-E 3 (sprites) + procedural generation
|
|
```
|
|
|
|
### Systems Programming Stack
|
|
```
|
|
Kernel: C + eBPF
|
|
Userspace: Go
|
|
Training: Python + WGAN-GP
|
|
Pattern: Event Stream → Ring Buffer → Feature Extraction → MicroML → Decision
|
|
```
|
|
|
|
## Technology Compatibility Rules
|
|
|
|
### Node.js Version Constraints
|
|
| Package | Min Node | Notes |
|
|
|---------|----------|-------|
|
|
| Next.js 14+ | 18.17+ | App Router requires 18.17+ |
|
|
| NestJS 10+ | 16+ | |
|
|
| Prisma 5+ | 16.13+ | |
|
|
| BullMQ 5+ | 18+ | |
|
|
| Grammy 1.x | 16+ | |
|
|
|
|
### Database Compatibility
|
|
| ORM | PostgreSQL | MySQL | SQLite | MongoDB |
|
|
|-----|-----------|-------|--------|---------|
|
|
| Prisma | Full | Full | Full | Full |
|
|
| TypeORM | Full | Full | Full | Full |
|
|
| Drizzle | Full | Full | Full | No |
|
|
| Sequelize | Full | Full | Full | No |
|
|
| Knex | Full | Full | Full | No |
|
|
|
|
### pgvector Requirements
|
|
- PostgreSQL 15+ recommended (14+ minimum)
|
|
- Prisma: use `$queryRawUnsafe` for `::vector` cast (not `$queryRaw`)
|
|
- Index type: IVFFlat (fast, approximate) or HNSW (slower build, faster query)
|
|
- Dimension limit: 2000 (OpenAI ada-002 = 1536, text-embedding-3-small = 1536)
|
|
|
|
### Next.js + NestJS Integration Rules
|
|
1. `NEXT_PUBLIC_*` vars baked at BUILD time — not runtime
|
|
2. Docker Compose reads `.env` NOT `.env.production`
|
|
3. Behind nginx: set `AUTH_TRUST_HOST=true` for NextAuth
|
|
4. API routes: `export const dynamic = "force-dynamic"` (no DB at build)
|
|
5. Mixed content: always use domain URL, never IP:port
|
|
|
|
### Docker Networking
|
|
- Shared network: all services can resolve by container name
|
|
- Port mapping: `host:container` — host port must be free
|
|
- DNS: container names as hostnames (e.g., `tip-postgres`, `tip-redis`)
|
|
- Health checks: always add for DB and Redis before app starts
|
|
|
|
### CSS Framework Compatibility
|
|
| Framework | React | Vue | Svelte | Angular |
|
|
|-----------|-------|-----|--------|---------|
|
|
| Tailwind CSS | Full | Full | Full | Full |
|
|
| styled-components | Full | No | No | No |
|
|
| Emotion | Full | No | No | No |
|
|
| CSS Modules | Full | Full | Full | Full |
|
|
|
|
## Anti-Compatible Combinations (DO NOT MIX)
|
|
|
|
| Bad Combo | Why | Use Instead |
|
|
|-----------|-----|-------------|
|
|
| TypeORM + Prisma in same project | Conflicting migration systems | Pick one ORM |
|
|
| Express + NestJS (raw) | NestJS wraps Express internally | Use NestJS decorators |
|
|
| Redux + Zustand in same project | Two state managers fighting | Pick one |
|
|
| Mongoose + Prisma MongoDB | Two ODMs, schema conflicts | Pick one |
|
|
| Webpack + Vite in same project | Two bundlers | Vite (modern) or Webpack (legacy) |
|
|
| npm + pnpm in same project | Lock file conflicts | Pick one package manager |
|
|
| .env.local + .env.production + .env | Loading order confusion | Use `.env` only in Docker |
|
|
|
|
## Migration Paths
|
|
|
|
### Express → NestJS
|
|
1. Create NestJS project alongside
|
|
2. Move routes → controllers one by one
|
|
3. Move middleware → guards/interceptors
|
|
4. Move services → injectable providers
|
|
5. Test each migration step
|
|
|
|
### Redux → Zustand
|
|
1. Create Zustand store matching Redux state shape
|
|
2. Replace `useSelector` → Zustand selectors
|
|
3. Replace `dispatch(action)` → store methods
|
|
4. Remove Redux boilerplate (reducers, action creators)
|
|
|
|
### Pages Router → App Router (Next.js)
|
|
1. Move `pages/api/*` → `app/api/*/route.ts`
|
|
2. Move `pages/*.tsx` → `app/*/page.tsx`
|
|
3. Add `'use client'` to interactive components
|
|
4. Replace `getServerSideProps` → server components
|
|
5. Replace `getStaticProps` → `generateStaticParams`
|
|
|
|
## Web Creation Stack (March 2026)
|
|
|
|
### Framework Selection
|
|
| Framework | Use When | Zero JS | Islands |
|
|
|-----------|----------|---------|---------|
|
|
| **Astro 6** | Marketing, content, portfolios (DEFAULT) | Yes | Yes |
|
|
| Next.js 16 | Full-stack React apps, dashboards | No | No |
|
|
| SvelteKit 5 | Animation-heavy, mobile-first | Compiles | No |
|
|
|
|
- Astro acquired by Cloudflare (Jan 2026) — first-class Workers integration
|
|
- Next.js 16: Turbopack default, React Compiler stable, PPR
|
|
- SvelteKit: 50%+ less JS than Next.js
|
|
|
|
### Animation & Motion
|
|
| Library | Version | Size | Use When |
|
|
|---------|---------|------|----------|
|
|
| GSAP | 3.14+ | ~28KB | ScrollTrigger, pin, scrub, timeline (100% FREE — Webflow) |
|
|
| Motion | 12.x | ~18KB | React animations, layout, gestures |
|
|
| Lenis | 1.3+ | ~14KB | Smooth scroll (industry standard) |
|
|
| AutoAnimate | 0.9 | ~2KB | Zero-config FLIP animations |
|
|
| Rive | runtime ~78KB | WASM | Interactive animations (state machines) |
|
|
| Lottie (dotlottie) | v3 | varies | After Effects animations |
|
|
|
|
### 3D & Visual Effects
|
|
| Library | Size | Use When |
|
|
|---------|------|----------|
|
|
| Three.js + R3F | ~150KB | Full 3D scenes, scroll-linked |
|
|
| Spline | embed | No-code 3D (limited precision) |
|
|
| curtains.js | ~30KB | DOM-synced WebGL (image distortion) |
|
|
| OGL | ~8KB | Minimal WebGL, custom shaders |
|
|
| tsParticles | config | Particle effects (<1000 particles) |
|
|
|
|
### Asset Pipeline
|
|
| Tool | Purpose |
|
|
|------|---------|
|
|
| Sharp.js | Image processing (AVIF/WebP/responsive) |
|
|
| glyphhanger | Font subsetting (60%+ reduction) |
|
|
| FFmpeg | Video encoding, frame extraction |
|
|
| nano-banana | AI image generation (Gemini) |
|
|
|
|
### Deployment
|
|
| Platform | Free Tier | Best For |
|
|
|----------|-----------|----------|
|
|
| **Cloudflare Pages** | Unlimited BW, 500 builds/mo | DEFAULT |
|
|
| Vercel | 100GB BW, 100 deploys/day | Next.js apps |
|
|
| Netlify | 100GB BW, 300 build min | Static + forms |
|
|
|
|
### RAG / Embeddings
|
|
| Component | Default | Alternative |
|
|
|-----------|---------|-------------|
|
|
| Vector DB | LanceDB (embedded, free) | Qdrant, Pinecone |
|
|
| Embeddings | OpenAI text-embedding-3-small ($0.02/MTok) | Gemini 2 (multimodal), Voyage (domain) |
|
|
| PDF parsing | PyMuPDF4LLM (Python) | pdf-parse (Node.js) |
|
|
| Chunking | Recursive 512tok/50overlap | Semantic, hierarchical |
|
|
|
|
### Forms & Validation
|
|
| Library | Version | Notes |
|
|
|---------|---------|-------|
|
|
| react-hook-form | v7 | Production. v8 beta — AVOID |
|
|
| Zod | v4 | Schema shared client+server (SSOT) |
|
|
| Turnstile | - | Free CAPTCHA, unlimited (Cloudflare) |
|
|
|
|
### CSS (Tailwind v4)
|
|
- `@theme` directive replaces tailwind.config.ts
|
|
- OKLCH color space for perceptually uniform palettes
|
|
- CSS-first configuration
|
|
|
|
### Anti-Compatible (Web Creation)
|
|
| Bad Combo | Why | Use Instead |
|
|
|-----------|-----|-------------|
|
|
| GSAP + CSS scroll-timeline for same element | Competing scroll handlers | Pick one per section |
|
|
| Lenis + native smooth scroll (scroll-behavior) | Double smooth-scrolling | Lenis only |
|
|
| Motion + GSAP in same component | Two animation systems fighting | Pick one per component |
|
|
| react-hook-form v7 + v8 in same project | Breaking API changes | Stick to v7 |
|
|
| Astro + full React hydration | Defeats zero-JS purpose | Use Astro islands (client:*) |
|
|
|
|
## Version Lock Warnings
|
|
|
|
When you see these in package.json, flag immediately:
|
|
- `"react": "^17"` with Next.js 14+ → needs React 18+
|
|
- `"prisma": "^4"` with Node 20+ → upgrade to Prisma 5+
|
|
- `"next-auth": "^4"` with App Router → consider NextAuth 5 beta
|
|
- `"bullmq": "^3"` with Redis 7+ → upgrade to BullMQ 5+
|
|
- `"gsap": "^3.11"` → upgrade to 3.14+ (all plugins now free)
|
|
- `"framer-motion"` → renamed to `motion` (npm install motion)
|
|
- Any `"*"` version → pin immediately
|