AI Assistant Backend API

Standalone Express.js API for AI chat functionality

This repository contains the backend REST API for the AI Assistant application. The frontend (React Native PWA + Android APK) is in a separate repository.

📋 Table of Contents

Overview
Architecture
Features
Prerequisites
Getting Started
API Endpoints
Environment Variables
Development
Deployment
Testing
Troubleshooting

Overview

This backend API provides:

AI Chat: Streaming chat with Claude (Anthropic) models
Authentication: Google OAuth + JWT-based auth
Conversations: CRUD operations for chat conversations
MCP Integration: Model Context Protocol server connections
Database: PostgreSQL for persistent storage

Technology Stack:

Framework: Express.js 4.21.2
Language: TypeScript 5
Database: PostgreSQL 14+
Deployment: Google Cloud Run
Default Port: 8080 (production), configurable for development

Architecture

┌─────────────────────────────────────────┐
│  Frontend (Separate Repository)        │
│  - React Native + Expo                 │
│  - PWA & Android APK                   │
│  - http://localhost:8081 (dev)         │
└──────────────┬──────────────────────────┘
               │
               │ HTTPS REST API
               │
┌──────────────▼──────────────────────────┐
│  Backend API (This Repository)         │
│  ├── /health                           │
│  ├── /api/ai (streaming chat)          │
│  ├── /api/auth (OAuth + JWT)           │
│  ├── /api/conversations                │
│  └── /api/mcp (tool management)        │
└──────────────┬──────────────────────────┘
               │
               ▼
       PostgreSQL Database

Features

Core Features

✅ Streaming AI Chat: Real-time streaming responses from Claude models
✅ Multiple Models: Support for Claude Sonnet 4.5, Opus 4.1, Haiku 3.5
✅ User Authentication: Google OAuth with JWT tokens
✅ Conversation Management: Save, load, and manage chat histories
✅ MCP Support: Connect to external tools (Gmail, Google Drive, Calendar)

Security Features

✅ CORS Protection: Configurable allowed origins
✅ Rate Limiting: Prevent API abuse
✅ Helmet: Security headers
✅ JWT Authentication: Secure API access
✅ Token Encryption: Encrypted storage of OAuth tokens

Production Features

✅ Health Checks: /health endpoint for monitoring
✅ Error Handling: Comprehensive error responses
✅ Logging: Structured logging for debugging
✅ Cloud Run Deployment: Automated CI/CD

Prerequisites

Node.js: 20+ (LTS recommended)
npm: 10+
PostgreSQL: 14+ (if using MCP features)
Anthropic API Key: From https://console.anthropic.com/
Google OAuth Credentials: From Google Cloud Console

Getting Started

1. Clone Repository

git clone https://github.com/sdhector/ai-agent-backend.git
cd ai-agent-backend

2. Install Dependencies

npm install

3. Configure Environment

IMPORTANT: GCP Secret Manager is the SINGLE SOURCE OF TRUTH for all secrets.

There is NO local .env file fallback. All secrets must be stored in GCP Secret Manager.

Local Development Setup

Authenticate with GCP:
```
gcloud auth application-default login
```

Verify secrets exist in Secret Manager:

gcloud secrets list --project=professional-website-462321

Required secrets (see SECRETS.md for complete list):
- google-client-id → GOOGLE_CLIENT_ID
- google-client-secret → GOOGLE_CLIENT_SECRET
- jwt-secret → JWT_SECRET
- anthropic-api-key → ANTHROPIC_API_KEY
- database-url → DATABASE_URL (if using MCP)

See SECRETS.md for detailed secret management instructions.

4. Run Locally

# Development mode (with auto-reload)
npm run dev

# Production mode
npm run build
npm start

Expected output:

Server running on port 8080
Health check: http://localhost:8080/health

5. Test Backend

# Health check
curl http://localhost:8080/health

# Expected response:
# {"status":"healthy","timestamp":"2025-11-10T10:00:00.000Z"}

API Endpoints

Health Check

GET /health

Returns server health status. No authentication required.

Response:

{
  "status": "healthy",
  "timestamp": "2025-11-10T10:00:00.000Z"
}

Authentication

Google OAuth Login

GET /api/auth/google

Redirects to Google OAuth consent screen.

Google OAuth Callback

GET /api/auth/google/callback?code=...

Handles OAuth callback and returns JWT token.

Check Auth Status

GET /api/auth/status
Authorization: Bearer <jwt_token>

Returns current user information.

AI Chat

Send Message (Streaming)

POST /api/ai
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "message": "Hello, how are you?",
  "provider": "claude",
  "model": "sonnet-4.5",
  "conversationId": "optional-uuid"
}

Returns Server-Sent Events (SSE) stream with AI response.

Conversations

List Conversations

GET /api/conversations
Authorization: Bearer <jwt_token>

Returns array of user's conversations.

Get Conversation

GET /api/conversations/:id
Authorization: Bearer <jwt_token>

Returns conversation details and messages.

Delete Conversation

DELETE /api/conversations/:id
Authorization: Bearer <jwt_token>

Deletes a conversation.

MCP (Model Context Protocol)

List MCP Servers

GET /api/mcp/servers
Authorization: Bearer <jwt_token>

Returns available MCP servers (Gmail, Drive, Calendar).

Connect to MCP Server

POST /api/mcp/connect
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "serverType": "gmail"
}

Initiates OAuth flow for MCP server connection.

Environment Variables

Required Variables

Variable	Description	Example
`ANTHROPIC_API_KEY`	Anthropic API key	`sk-ant-...`
`JWT_SECRET`	Secret for signing JWT tokens	`your-32-char-secret`
`GOOGLE_CLIENT_ID`	Google OAuth client ID	`123.apps.googleusercontent.com`
`GOOGLE_CLIENT_SECRET`	Google OAuth client secret	`GOCSPX-...`

Optional Variables

Variable	Description	Default
`PORT`	Backend server port	`8080`
`BACKEND_PORT`	Alternative port variable	`8080`
`FRONTEND_URL`	Frontend URL for OAuth redirects	`http://localhost:8081`
`DATABASE_URL`	PostgreSQL connection string	-
`MCP_ENABLED`	Enable MCP features	`false`
`NODE_ENV`	Environment (development/production)	`development`
`ENABLE_RATE_LIMIT`	Enable rate limiting	`true`
`ENABLE_LOGGING`	Enable request logging	`true`

Generating Secrets

# JWT Secret (32 bytes, base64)
openssl rand -base64 32

# Encryption Key (32 bytes, base64)
openssl rand -base64 32

# Token Encryption Key (32 bytes, hex)
openssl rand -hex 32

Development

Project Structure

ai-assistant-backend/
├── config/                 # Configuration files
│   └── index.ts           # Main config
├── database/              # Database setup
│   └── index.ts          # PostgreSQL connection
├── middleware/            # Express middleware
│   ├── auth.ts           # JWT authentication
│   └── cors.ts           # CORS configuration
├── providers/             # AI providers
│   └── claude.ts         # Anthropic Claude provider
├── routes/                # API routes
│   ├── ai.js             # Chat endpoints
│   ├── auth.ts           # Authentication endpoints
│   ├── conversations.ts  # Conversation CRUD
│   ├── health.js         # Health check
│   └── mcp.ts            # MCP endpoints
├── services/              # Business logic
│   ├── mcp/              # MCP service implementations
│   └── encryption.ts     # Token encryption
├── types/                 # TypeScript type definitions
├── utils/                 # Utility functions
├── server.js              # Entry point
├── package.json
├── tsconfig.json
├── Dockerfile
└── cloudbuild.yaml

Development Workflow

Make changes to code
Test locally: npm run dev
Run tests: npm test
Type check: npm run typecheck
Commit changes: git commit -m "feat: your changes"
Push to main: Triggers auto-deployment to Cloud Run

Adding New Endpoints

Create route file in routes/
Implement route logic
Add authentication middleware if needed
Register route in server.js
Test with curl or Postman
Update API documentation

Deployment

Google Cloud Run

This backend automatically deploys to Google Cloud Run when you push to the main branch.

Prerequisites

Google Cloud Project with billing enabled
Cloud Run API enabled
Cloud Build API enabled
GitHub repository connected to Cloud Build

Manual Deployment

# Authenticate with Google Cloud
gcloud auth login
gcloud config set project YOUR_PROJECT_ID

# Build and deploy
gcloud builds submit --config cloudbuild.yaml

# Verify deployment
gcloud run services describe ai-assistant-backend --region=us-central1

Environment Variables (Production)

Set environment variables in Cloud Run:

# Using gcloud CLI
gcloud run services update ai-assistant-backend \
  --region=us-central1 \
  --set-env-vars="NODE_ENV=production,PORT=8080,FRONTEND_URL=https://your-pwa.web.app"

Or use Google Secret Manager for sensitive values:

# Create secret
echo -n "your-jwt-secret" | gcloud secrets create jwt-secret --data-file=-

# Grant access to Cloud Run
gcloud secrets add-iam-policy-binding jwt-secret \
  --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

# Use in Cloud Run
gcloud run services update ai-assistant-backend \
  --region=us-central1 \
  --set-secrets=JWT_SECRET=jwt-secret:latest

Deployment URL

After deployment, your backend will be available at:

https://ai-assistant-backend-<hash>-uc.a.run.app

Update this URL in your frontend's environment configuration.

Testing

Run Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Manual API Testing

Test Health Endpoint

curl http://localhost:8080/health

Test Authentication (requires OAuth flow)

# Step 1: Visit OAuth URL in browser
open http://localhost:8080/api/auth/google

# Step 2: Complete OAuth flow, get JWT token

# Step 3: Use JWT token for authenticated requests
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:8080/api/auth/status

Test Chat Endpoint

curl -X POST http://localhost:8080/api/ai \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello!",
    "provider": "claude",
    "model": "sonnet-4.5"
  }'

Troubleshooting

Issue: Port Already in Use

Error: Error: listen EADDRINUSE: address already in use :::8080

Solution:

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or use a different port
PORT=8081 npm run dev

Issue: CORS Errors

Error: Access-Control-Allow-Origin header missing

Solution:

Check config/index.ts → getCorsOrigins()
Add your frontend URL to allowed origins
Restart backend server
Hard refresh frontend

Issue: Database Connection Failed

Error: Error: connect ECONNREFUSED

Solution:

Verify PostgreSQL is running
Check DATABASE_URL in .env
Test connection: psql $DATABASE_URL
Check firewall rules

Issue: JWT Token Invalid

Error: 401 Unauthorized

Solution:

Verify JWT_SECRET matches between frontend and backend
Check token expiration (default 7 days)
Try logging in again to get fresh token
Check Authorization header format: Bearer <token>

Issue: Cloud Run Deployment Fails

Error: Build fails or service crashes

Solution:

Check Cloud Build logs: gcloud builds list --limit=5
View build details: gcloud builds log BUILD_ID
Common issues:
- Missing environment variables
- Docker build errors
- Health check failing

Test Docker image locally:

docker build -t ai-assistant-backend .
docker run -p 8080:8080 --env-file .env ai-assistant-backend

Contributing

Fork the repository
Create feature branch: git checkout -b feature/your-feature
Make changes and test thoroughly
Commit changes: git commit -m "feat: add your feature"
Push to branch: git push origin feature/your-feature
Create Pull Request

License

This project is licensed under the ISC License.

Support

For issues, questions, or contributions:

GitHub Issues: https://github.com/sdhector/ai-agent-backend/issues
Documentation: See /docs folder for detailed guides

Related Repositories

Frontend: https://github.com/sdhector/ai-agent-frontend (React Native PWA + Android APK)

Last Updated: November 10, 2025

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
__tests__		__tests__
config		config
constants		constants
database		database
middleware		middleware
providers		providers
routes		routes
services		services
types		types
utils		utils
.env.example		.env.example
.gitignore		.gitignore
CLOUD_RUN_STARTUP_FIX.md		CLOUD_RUN_STARTUP_FIX.md
DEPLOYMENT.md		DEPLOYMENT.md
Dockerfile		Dockerfile
README.md		README.md
SECRETS.md		SECRETS.md
SECURITY_AUDIT.md		SECURITY_AUDIT.md
check-secrets.py		check-secrets.py
cloudbuild.yaml		cloudbuild.yaml
package-lock.json		package-lock.json
package.json		package.json
server-app.js		server-app.js
server.js		server.js
tsconfig.json		tsconfig.json

sdhector/ai-agent-backend

Folders and files

Latest commit

History

Repository files navigation

AI Assistant Backend API

📋 Table of Contents

Overview

Architecture

Features

Core Features

Security Features

Production Features

Prerequisites

Getting Started

1. Clone Repository

2. Install Dependencies

3. Configure Environment

Local Development Setup

4. Run Locally

5. Test Backend

API Endpoints

Health Check

Authentication

Google OAuth Login

Google OAuth Callback

Check Auth Status

AI Chat

Send Message (Streaming)

Conversations

List Conversations

Get Conversation

Delete Conversation

MCP (Model Context Protocol)

List MCP Servers

Connect to MCP Server

Environment Variables

Required Variables

Optional Variables

Generating Secrets

Development

Project Structure

Development Workflow

Adding New Endpoints

Deployment

Google Cloud Run

Prerequisites

Manual Deployment

Environment Variables (Production)

Deployment URL

Testing

Run Tests

Manual API Testing

Test Health Endpoint

Test Authentication (requires OAuth flow)

Test Chat Endpoint

Troubleshooting

Issue: Port Already in Use

Issue: CORS Errors

Issue: Database Connection Failed

Issue: JWT Token Invalid

Issue: Cloud Run Deployment Fails

Contributing

License

Support

Related Repositories

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages