TCDynamics WorkFlowAI

AI-powered automation platform for French SMEs.

Hybrid system: Vercel serverless API + React frontend. Express backend exists for local dev only.

Project Structure

• apps/frontend — React 18 + Vite; deployed on Vercel (includes /api serverless routes copied from root api/ during CI)
• api — Vercel serverless functions (contact, demo, chat, vision, polar, health)
• apps/backend — Express server for local development/testing (not deployed to production)
• packages/shared-types, packages/shared-utils — shared TypeScript packages (must be built before type-checking; see AGENTS.md)
• tests/e2e — Playwright e2e tests
• docker/ — local docker-compose + nginx config
• docs/ — project documentation (environment setup, migrations, security, testing, etc.)
• scripts/ — deployment and utility scripts (e.g. deploy-vercel.ps1, ship.ps1)
• tools/ — shared configs (Prettier, Jest, CommitLint, etc.) and tool scripts

Quick Start

npm install           # installs root + workspaces
npm run dev           # runs frontend + Vercel dev (API functions) with optimized settings
# or per app
npm run dev:frontend  # frontend only (Vite dev server)
npm run dev:vercel    # Vercel dev server (API functions) - includes 32KB header size limit
npm run dev:backend   # local Express only (optional)
npm run dev:all       # all three together

Note: The npm run dev command automatically configures Node.js to accept larger HTTP headers (32KB) to accommodate Clerk authentication tokens. If you encounter 431 Request Header Fields Too Large errors, ensure you're using npm run dev and not just npm run dev:frontend.

Environment Variables

Required for API functions:

• CLERK_SECRET_KEY - Clerk secret key for authentication (get from Clerk Dashboard)
• MONGODB_URI - MongoDB Atlas connection string

Frontend:

• VITE_CLERK_PUBLISHABLE_KEY - Clerk publishable key (starts with pk_)

See docs/development/environment-setup.md for complete documentation of all environment variables.

⚠️ Important: Use CLERK_SECRET_KEY (not CLERK_API_KEY) for backend authentication.

Testing & Linting

npm run test          # frontend + backend
npm run lint          # frontend + backend
npm run type-check

ESLint Configuration

The project uses a hierarchical ESLint configuration with flat config format:

• Root: eslint.config.js - Shared configuration extending frontend config for tests/e2e
• Frontend: apps/frontend/eslint.config.js - Main configuration with React/TSX rules, accessibility (WCAG 2.1 AA), Tailwind CSS, and import organization
• Backend: apps/backend/eslint.config.js - Node.js/Express specific rules with relaxed frontend restrictions

Both frontend and backend use ESLint v9 with consistent TypeScript ESLint versions for unified code quality standards. The root config provides special handling for e2e tests with allowDefaultProject enabled.

Shared Configuration Files

Common configuration files are centralized in tools/configs/ for consistency across workspaces:

• Prettier: .prettierrc, .prettierignore - Code formatting rules
• CommitLint: commitlint.config.cjs - Commit message validation
• Jest: jest.config.cjs - Root-level Jest configuration (backend only)
• Components: components.json - ShadCN UI component configuration

Workspace scripts reference these configs using relative paths (e.g., --config ../../tools/configs/.prettierrc).

Deployment

• Frontend + serverless API: Vercel
• Express backend: local/dev only

Note: Azure Functions were previously used and have been archived; the archive is not in the current repository. See docs/migrations/azure-vision.md for migration tracking and planning.

Vercel Deployment

Configuration: Vercel deployment uses a single root-level vercel.json configuration file (located at the project root). This is the canonical source for all Vercel settings including:

• Build commands and output directories (configured for monorepo structure)
• Security headers (including Cross-Origin-Embedder-Policy: credentialless; see docs/security/coep-config.md for rationale)
• Rewrites, redirects, and caching rules
• Environment variables

Rationale: Using a single root config prevents configuration drift, ensures consistency across deployments, and aligns with Vercel's best practices for monorepo deployments. The previous apps/frontend/vercel.json has been renamed to vercel.json.backup for reference.

For production deployment to Vercel, you have two options:

Option 1: Frontend + API (Full Deployment)

npm run deploy:vercel

This script deploys both the frontend and API serverless functions. Note: Vercel Hobby plan has a limit of 12 serverless functions.

Option 2: Frontend Only (Static Build)

npm run deploy:vercel:frontend

This script deploys only the frontend static build without serverless functions. Use this if you're hitting the 12 function limit or if your APIs are hosted elsewhere.

Note: Automatic deployments are configured via GitHub Actions on pushes to the main branch. Use the scripts above for manual deployments.

Logging & Privacy

PII Protection

Serverless API functions hash sensitive identifiers (orgId, userId) before logging using SHA-256.

• Identifiers are hashed with optional salt from PII_HASH_SALT or IP_HASH_SALT environment variables
• Error objects are sanitized to log only message and stack (dev only)
• See api/polar/create-checkout-session.js for implementation

Log Retention & Access Control

• Retention: Logs retained per Vercel's default retention policy (typically 30 days for Hobby, 90 days for Pro/Enterprise)
• Access Control: Logs accessible only to authorized operations team members via Vercel dashboard
• Storage: Logs stored in Vercel Logs with encryption at rest
• Audit: All log access is tracked through Vercel's audit logs

Documentation

In-repo documentation lives in docs/ (environment setup, migrations, security, testing, etc.). Additional detailed project documentation, architecture diagrams, and implementation guides may be maintained locally in the md/ directory (excluded from this repository).