Get Started with TenderCheck AI

By the end of this guide you will have a fully functional local instance of TenderCheck AI with the React frontend running on port 3000, the Express/TypeScript backend running on port 3001, and complete AI-powered tender analysis and proposal validation connected to a live Turso database and Gemini 2.5 Flash.

Prerequisites

Make sure the following are available before you begin:

Node.js LTS 22+ — nodejs.org
Turso account + CLI — turso.tech (free tier is sufficient)
Google AI Studio API key — aistudio.google.com
Git

Setup Steps

Clone the Repository

git clone https://github.com/elecodes/TenderCheck-AI.git
cd TenderCheck-AI

Install Backend Dependencies

cd backend
npm install

Configure Backend Environment

Create a .env file inside the backend/ directory by copying the example and filling in your credentials:

PORT=3001
NODE_ENV=development

# Gemini API Key (Get from Google AI Studio)
GOOGLE_GENAI_API_KEY=your_gemini_api_key_here

# Standard Google AI Key (Required by Genkit 1.28.0+)
GOOGLE_API_KEY=your_google_ai_key_here

# Turso Configuration
# Auth Token (Get from 'turso db tokens create')
TURSO_AUTH_TOKEN=your_turso_auth_token_here

# Database URL (libsql://your-db.turso.io)
TURSO_DB_URL=libsql://your-db-name.turso.io

# JWT Secret (Generate a strong secret for production)
JWT_SECRET=your_jwt_secret_here

# CORS Configuration (Add your frontend URLs)
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# LangSmith Configuration
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=TenderCheckAI

Variable	Required	Description
`PORT`	Yes	Port the backend HTTP server listens on (defaults to `3001` if not set)
`NODE_ENV`	Yes	Runtime mode — use `development` locally
`GOOGLE_GENAI_API_KEY`	Yes	Primary Gemini API key from Google AI Studio
`GOOGLE_API_KEY`	Yes	Standard Google AI key — required by Genkit 1.28.0+
`TURSO_AUTH_TOKEN`	Yes	Auth token from `turso db tokens create`
`TURSO_DB_URL`	Yes	Turso connection URL, e.g. `libsql://your-db.turso.io`
`JWT_SECRET`	Yes	Secret used to sign JWT session tokens
`ALLOWED_ORIGINS`	Yes	Comma-separated list of allowed CORS origins
`LANGCHAIN_API_KEY`	No	LangSmith API key for AI observability and tracing
`LANGCHAIN_PROJECT`	No	LangSmith project name (defaults to `TenderCheckAI`)

Initialize the Turso Database

Create a new Turso database and generate an access token using the Turso CLI:

# Create a new database
turso db create tendercheck-ai

# Retrieve the database URL
turso db show tendercheck-ai --url

# Generate an auth token
turso db tokens create tendercheck-ai

Copy the URL and token into your backend/.env. The database schema (tables for users, tenders, and analyses) initialises automatically the first time the backend starts — no manual migration step is required.

Install Frontend Dependencies

cd ../frontend
npm install

Configure Frontend Environment

Create a .env file inside the frontend/ directory:

# Backend API base URL
VITE_API_BASE_URL=http://localhost:3001

# Google OAuth Client ID (from Google Cloud Console)
VITE_GOOGLE_CLIENT_ID=your_google_client_id.apps.googleusercontent.com

VITE_API_BASE_URL points the React app at your local backend. VITE_GOOGLE_CLIENT_ID is required only if you want to enable Google Sign-In locally; you can leave it blank to use email/password auth only.

Start the Backend

Open a terminal in the backend/ directory and run:

cd backend
npm run dev

The backend starts on port 3001 using tsx watch for hot-reload. You should see:

🚀 [Server] Initializing...
📡 [Server] Target Port: 3001
🌍 [Server] Node Env: development
✅ [Server] Ready and listening on port 3001

Start the Frontend

Open a second terminal in the frontend/ directory and run:

cd ../frontend
npm run dev

Vite starts the React application on port 3000.

Try the Application

Open http://localhost:3000 in your browser.

Click Register and create a new account.
Log in with your credentials.
On the dashboard, upload docs/Testing_docs/Pliego_Tender_IT_Security.pdf as the tender document.
Wait for the AI to extract all requirements — this typically takes 15–30 seconds.
Once the tender analysis is complete, upload docs/Testing_docs/Oferta_Offer_IT_Security.pdf as the proposal.
Review the compliance validation report, click any citation badge to inspect the source text, and export a PDF report.

The repository includes two sample documents in docs/Testing_docs/ for end-to-end testing:

Pliego_Tender_IT_Security.pdf — an IT Security public tender document. Use this to test the Tender Analysis flow.
Oferta_Offer_IT_Security.pdf — a vendor offer for the same contract. Use this to test the Proposal Validation flow (requires a completed tender analysis first).

Running Tests

TenderCheck AI enforces strict quality gates across unit, integration, and end-to-end layers. Unit tests (Vitest — run from backend/ or frontend/):

npm test

End-to-end tests (Playwright — run from the repo root):

npx playwright test

Coverage report (enforces 100% domain layer, 92%+ global):

npm run test:coverage

To view the Playwright HTML report after a test run:

npx playwright show-report

Open two terminal windows side by side — one in backend/ running npm run dev, and one in frontend/ running npm run dev. Both support hot-reload, so code changes are reflected instantly.

Get Started

Core Features

Architecture

Configuration & Deployment

Get Started with TenderCheck AI

Prerequisites

Setup Steps

Running Tests

​Prerequisites

​Setup Steps

​Running Tests

Prerequisites

Setup Steps

Running Tests