docs: map existing codebase
This commit is contained in:
164
.planning/codebase/STACK.md
Normal file
164
.planning/codebase/STACK.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Technology Stack
|
||||
|
||||
**Analysis Date:** 2026-04-27
|
||||
|
||||
## Languages
|
||||
|
||||
**Primary:**
|
||||
- TypeScript 5.9.3 (server), 5.7.3 (client) - Strict mode enabled, full type safety across codebase
|
||||
|
||||
**Secondary:**
|
||||
- JavaScript (build outputs, scripts)
|
||||
- HTML/CSS (frontend templates)
|
||||
|
||||
## Runtime
|
||||
|
||||
**Environment:**
|
||||
- Node.js (version not pinned, assumed LTS) - Used for both server and client dev/build
|
||||
- ES2023 target (server), ES2022 target (client)
|
||||
|
||||
**Package Manager:**
|
||||
- npm - Lockfiles present for both client and server
|
||||
|
||||
## Frameworks
|
||||
|
||||
**Core Frontend:**
|
||||
- React 19.2.0 - UI framework
|
||||
- React Router DOM 7.12.0 - Client-side routing
|
||||
- Vite 7.2.4 - Build tool and dev server
|
||||
|
||||
**Core Backend:**
|
||||
- NestJS 11.0.1 - Web framework with TypeScript-first design
|
||||
- Express (via `@nestjs/platform-express`) - Underlying HTTP server
|
||||
|
||||
**Frontend Styling:**
|
||||
- Tailwind CSS 4.1.18 - Utility-first CSS framework
|
||||
- `@tailwindcss/vite` plugin for Vite integration
|
||||
|
||||
**Testing & Development:**
|
||||
- Jest 30.0.0 - Test runner (server-side only, configured in package.json)
|
||||
- ts-jest - TypeScript support for Jest
|
||||
- Supertest 7.0.0 - HTTP assertion library (server integration tests)
|
||||
- @vitejs/plugin-react - React fast refresh for Vite
|
||||
|
||||
## Key Dependencies
|
||||
|
||||
**Critical Server:**
|
||||
- `@prisma/client` 7.2.0 - ORM and database abstraction layer
|
||||
- `prisma` 7.2.0 - CLI and schema management tool
|
||||
- `@anthropic-ai/sdk` 0.71.2 - Claude API for on-demand German translations
|
||||
- `socket.io` 4.8.3 - WebSocket library for real-time communication
|
||||
- `@nestjs/websockets` 11.1.12 - NestJS WebSocket integration
|
||||
- `@nestjs/platform-socket.io` 11.1.12 - Socket.io adapter for NestJS
|
||||
- `@nestjs/jwt` 11.0.2 - JWT authentication provider
|
||||
- `@nestjs/passport` 11.0.5 - Passport.js integration for authentication
|
||||
- `passport-jwt` 4.0.1 - JWT strategy for Passport
|
||||
- `bcrypt` 6.0.0 - Password hashing
|
||||
- `class-validator` 0.14.3 - Request DTO validation
|
||||
- `class-transformer` 0.5.1 - DTO transformation
|
||||
- `@nestjs/swagger` 11.2.5 - OpenAPI/Swagger documentation
|
||||
- `@nestjs/config` 4.0.2 - Environment configuration management
|
||||
- `dotenv` 17.2.3 - .env file loading
|
||||
|
||||
**Critical Client:**
|
||||
- `axios` 1.13.2 - HTTP client library for API requests
|
||||
- `socket.io-client` 4.8.3 - WebSocket client for real-time updates
|
||||
- `zustand` 5.0.10 - Client state management (auth store)
|
||||
- `@tanstack/react-query` 5.90.19 - Server state and data fetching (caching, synchronization)
|
||||
- `react-router-dom` 7.12.0 - Client-side routing
|
||||
- `framer-motion` 12.26.2 - Animation library
|
||||
- `lucide-react` 0.562.0 - Icon library (SVG icons)
|
||||
- `clsx` 2.1.1 - Conditional CSS class utilities
|
||||
- `tailwind-merge` 3.4.0 - Tailwind class merging utility
|
||||
|
||||
**Development (Backend):**
|
||||
- `@nestjs/cli` 11.0.0 - NestJS code generation and project scaffolding
|
||||
- `@nestjs/schematics` 11.0.0 - Code generators for NestJS
|
||||
- `prettier` 3.4.2 - Code formatter
|
||||
- `eslint` 9.18.0 - Linting
|
||||
- `typescript-eslint` 8.20.0 - TypeScript ESLint support
|
||||
- `tsx` 4.21.0 - TypeScript execution (used for seed scripts)
|
||||
- `tsconfig-paths` 4.2.0 - TypeScript path alias resolution
|
||||
- `ts-node` 10.9.2 - TypeScript REPL and script runner
|
||||
- `ts-loader` 9.5.2 - TypeScript webpack loader
|
||||
|
||||
**Development (Frontend):**
|
||||
- `eslint` 9.39.1 - Linting
|
||||
- `typescript-eslint` 8.46.4 - TypeScript ESLint support
|
||||
- `eslint-plugin-react-hooks` 7.0.1 - React Hooks linting rules
|
||||
- `eslint-plugin-react-refresh` 0.4.24 - Vite React refresh linting
|
||||
|
||||
## Configuration
|
||||
|
||||
**Environment:**
|
||||
- Server loads from `.env` file (see `.env.example`):
|
||||
- `DATABASE_URL` - PostgreSQL connection string
|
||||
- `JWT_SECRET` - Secret key for signing tokens
|
||||
- `JWT_EXPIRES_IN` - Token expiration time (default "7d")
|
||||
- `PORT` - Server port (default 5000)
|
||||
- `NODE_ENV` - Environment (development/production)
|
||||
- `CORS_ORIGINS` - Comma-separated list of allowed origins
|
||||
- `ANTHROPIC_API_KEY` - Claude API key for translations (optional)
|
||||
- `UPLOAD_DIR` - Directory for file uploads
|
||||
- `MAX_FILE_SIZE` - Maximum upload file size
|
||||
|
||||
- Client loads from `.env` or `.env.local`:
|
||||
- `VITE_API_URL` - Backend API base URL (e.g., `http://localhost:5000/api`)
|
||||
- WebSocket URL derived automatically by removing `/api` suffix
|
||||
|
||||
**TypeScript:**
|
||||
- Server: `server/tsconfig.json` with target ES2023, decorators enabled
|
||||
- `strictNullChecks: true`
|
||||
- `forceConsistentCasingInFileNames: true`
|
||||
- `noImplicitAny: false` (allows implicit any in some cases)
|
||||
- Path aliases via `baseUrl: ./`
|
||||
|
||||
- Client: `client/tsconfig.app.json` with target ES2022, strict mode
|
||||
- `strict: true` - All strict options enabled
|
||||
- `noUnusedLocals: true`, `noUnusedParameters: true`
|
||||
- `jsx: react-jsx` - JSX without React import required
|
||||
- Path alias `@/*` → `./src/*`
|
||||
|
||||
**Build:**
|
||||
- Client Vite config: `client/vite.config.ts`
|
||||
- Dev server port 5173
|
||||
- API proxy `/api` → `http://localhost:5000`
|
||||
- React plugin with React 19 support
|
||||
- Tailwind CSS Vite plugin
|
||||
- Type checking via `tsc -b` before build
|
||||
|
||||
- Server NestJS config: `server/nest-cli.json` (if exists)
|
||||
- Build output to `dist/`
|
||||
|
||||
## Platform Requirements
|
||||
|
||||
**Development:**
|
||||
- Node.js LTS (tested with v22)
|
||||
- npm (lockfiles version management)
|
||||
- PostgreSQL 16+ (via Docker Compose)
|
||||
- Docker & Docker Compose (for database)
|
||||
- Git
|
||||
|
||||
**Production:**
|
||||
- Node.js LTS
|
||||
- PostgreSQL 16+ (managed service or self-hosted)
|
||||
- Anthropic API key for translations (optional but recommended)
|
||||
- File storage: Local filesystem or cloud storage (currently local via `./uploads`)
|
||||
|
||||
## Database
|
||||
|
||||
**PostgreSQL 16 Alpine** (via Docker Compose):
|
||||
- Port 5432 (internal), 5433 (exposed for dev)
|
||||
- Database name: `dimension47`
|
||||
- Default credentials in docker-compose (dev only)
|
||||
- pgAdmin 4 included for database management (port 5050)
|
||||
|
||||
**Prisma Configuration:**
|
||||
- Schema: `server/prisma/schema.prisma`
|
||||
- Generator: Prisma Client with CommonJS module format
|
||||
- Adapter: `@prisma/adapter-pg` for optimized PostgreSQL queries
|
||||
- Output: `src/generated/prisma/`
|
||||
|
||||
---
|
||||
|
||||
*Stack analysis: 2026-04-27*
|
||||
Reference in New Issue
Block a user