Installation

System Requirements

Before you begin, ensure your system meets these requirements:

Node.js

Version 20 or higherCheck your version:

node --version

Package Manager

npm, yarn, or pnpmAny modern package manager works:

npm (comes with Node.js)
yarn 1.22+
pnpm 8+

Recommended: Use Node.js 20 LTS for best compatibility and performance.

Installation Methods

Choose your preferred installation method:

npm
yarn
pnpm

Install with npm

Clone Repository

git clone https://github.com/jose-miserol/gima-ai-chatbot.git
cd gima-ai-chatbot

Install Dependencies

npm install

This installs all required packages:

Next.js 16.0: React framework
React 19: UI library
Vercel AI SDK v5: AI integration
Tailwind CSS 4: Styling
Zod 4: Schema validation
And more (see package.json)

Setup Environment

cp .env.example .env.local

Edit .env.local with your configuration (see Environment Variables below)

Start Development Server

npm run dev

Server starts at http://localhost:3000

Install with Yarn

Clone Repository

git clone https://github.com/jose-miserol/gima-ai-chatbot.git
cd gima-ai-chatbot

Install Dependencies

yarn install

Setup Environment

cp .env.example .env.local

Edit .env.local with your API keys

Start Development Server

yarn dev

Install with pnpm

Clone Repository

git clone https://github.com/jose-miserol/gima-ai-chatbot.git
cd gima-ai-chatbot

Install Dependencies

pnpm install

Setup Environment

cp .env.example .env.local

Edit .env.local with your API keys

Start Development Server

pnpm dev

Environment Variables

GIMA uses environment variables for configuration. All variables are validated at startup using Zod schemas.

Required Variables

These API keys are required for the chatbot to function:

GROQ_API_KEY

string

required

GROQ API key for LLaMA 3.3 language model (main chat functionality)

Format: Must start with gsk_
Get it: console.groq.com/keys
Free tier: Yes, generous limits

GROQ_API_KEY=gsk_your_api_key_here

GOOGLE_GENERATIVE_AI_API_KEY

string

required

Google Gemini API key for voice transcription and image analysis

Format: Must start with AIza
Get it: makersuite.google.com/app/apikey
Free tier: Yes, 1500 requests/day

GOOGLE_GENERATIVE_AI_API_KEY=AIzaYourAPIKeyHere

Optional Variables

NODE_ENV

string

default:"development"

Runtime environment

Values: development, production, test
Effect: Changes logging, error handling, and security headers

NODE_ENV=development

NEXT_PUBLIC_APP_URL

string

default:"http://localhost:3000"

Base URL of the application (for production deployments)

NEXT_PUBLIC_APP_URL=https://your-domain.com

Feature Flags

Control optional features using these environment variables:

NEXT_PUBLIC_ENABLE_CHAT_PERSISTENCE

boolean

default:"false"

Enable localStorage persistence for chat history

NEXT_PUBLIC_ENABLE_CHAT_PERSISTENCE=true

When enabled:

Messages persist across page refreshes
Stored in browser localStorage with key gima_chat_history
Users can clear history manually

When disabled:

Chat history only exists in memory
Cleared on page refresh

NEXT_PUBLIC_FEATURE_VOICE_COMMANDS

boolean

default:"false"

Enable voice-activated work order commands

NEXT_PUBLIC_FEATURE_VOICE_COMMANDS=true

NEXT_PUBLIC_FEATURE_PDF_READER

boolean

default:"false"

Enable PDF upload and analysis

NEXT_PUBLIC_FEATURE_PDF_READER=true

Complete .env.local Example

.env.local

# ========================================
# Required API Keys
# ========================================
GROQ_API_KEY=gsk_your_groq_api_key_here
GOOGLE_GENERATIVE_AI_API_KEY=AIzaYourGoogleAPIKeyHere

# ========================================
# Environment Configuration
# ========================================
NODE_ENV=development
NEXT_PUBLIC_APP_URL=http://localhost:3000

# ========================================
# Feature Flags
# ========================================
NEXT_PUBLIC_ENABLE_CHAT_PERSISTENCE=true
NEXT_PUBLIC_FEATURE_VOICE_COMMANDS=true
NEXT_PUBLIC_FEATURE_PDF_READER=true

Security: Never commit .env.local to version control. It’s already in .gitignore.

Key Technologies

GIMA is built with modern, production-ready technologies:

Next.js 16

App Router with server components

File-based routing
Server Actions for API calls
Built-in optimization

React 19

Latest React with concurrent features

Improved performance
Better Suspense
Enhanced hooks

Vercel AI SDK v5

AI framework for chat and streaming

useChat hook
Streaming responses
Tool calling support

Tailwind CSS 4

Utility-first CSS framework

Responsive design
Dark mode support
Custom theme

TypeScript 5

Type safety throughout

Strict mode enabled
Full IDE support
Runtime validation

Zod 4

Schema validation for data

Type inference
Runtime safety
Error handling

Available Scripts

The project includes several npm scripts for development and testing:

# Start development server with hot reload
npm run dev

# Open at http://localhost:3000

Project Structure

Understanding the project layout:

gima-ai-chatbot/
├── app/
│   ├── api/                    # API routes
│   │   └── chat/
│   │       └── route.ts       # Main chat endpoint
│   ├── actions/               # Server Actions
│   │   ├── voice.ts          # Voice transcription
│   │   ├── vision.ts         # Image analysis
│   │   └── files.ts          # PDF processing
│   ├── components/           # React components
│   │   ├── features/         # Feature components
│   │   │   ├── chat/        # Chat UI
│   │   │   └── voice/       # Voice components
│   │   ├── ai-elements/     # AI-generated UI
│   │   └── ui/              # Base UI (shadcn/ui)
│   ├── config/              # Configuration
│   │   └── env.ts          # Environment validation
│   ├── hooks/              # Custom React hooks
│   │   ├── use-persistent-chat.ts
│   │   ├── use-voice-input.ts
│   │   └── use-file-submission.ts
│   ├── lib/                # Libraries and utilities
│   │   ├── ai/            # AI configuration
│   │   │   └── chat-tools.ts  # Tool definitions
│   │   ├── services/      # Business logic
│   │   │   ├── chat-service.ts
│   │   │   └── backend-api.ts
│   │   └── schemas/       # Zod schemas
│   ├── types/             # TypeScript types
│   └── page.tsx          # Main page
├── public/               # Static assets
├── tests/               # Test files
├── .env.example        # Environment template
└── package.json       # Dependencies

Key files to explore:

app/components/features/chat/chat.tsx - Main chat component
app/api/chat/route.ts - Chat API endpoint
app/lib/ai/chat-tools.ts - AI tool definitions

Verification Steps

After installation, verify everything works:

Check Server Status

Server should start without errors:

npm run dev

Expected output:

✓ Ready in 2.5s
○ Local:   http://localhost:3000

Test Basic Chat

Open http://localhost:3000
Type: “Hola, ¿qué puedes hacer?”
Press Enter

You should see a streaming response from the AI.

Test Voice Input (Optional)

Click the microphone icon
Allow browser microphone access
Say something like “Prueba de voz”
Text should appear in the input box

Test Image Analysis (Optional)

Click the image upload icon
Upload a photo of equipment or machinery
The AI should analyze and describe the image

Run Tests

Ensure all tests pass:

npm test

All tests should pass with green checkmarks.

Troubleshooting

Common issues and solutions:

Installation fails with module not found errors

Symptoms:

Error: Cannot find module '@ai-sdk/react'

Solution:

Delete node_modules and lock file:

rm -rf node_modules package-lock.json
npm install

Ensure you’re using Node.js 20+:
```
node --version
```

ZodError: Expected string, received undefined

Symptoms: Server crashes on startup with Zod validation errors for environment variables.Cause: Missing or incorrectly formatted API keys in .env.local.Solution:

Verify .env.local exists and has correct keys
Check key formats:
- GROQ: starts with gsk_
- Google: starts with AIza

On Windows, ensure UTF-8 encoding (not UTF-16):

$content = Get-Content .env.local -Raw -Encoding Unicode
[System.IO.File]::WriteAllText((Resolve-Path .env.local), $content, [System.Text.UTF8Encoding]::new($false))

Chat not responding / Streaming fails

Symptoms: Messages don’t appear, or chat shows error state.Solution:

Check browser console (F12) for errors
Verify API keys are valid:
- Test GROQ key at console.groq.com
- Test Google key at AI Studio
Check rate limits (GROQ: 30 req/min)
Restart dev server: npm run dev

Voice input not working

Symptoms: Microphone button does nothing or shows error.Solution:

Grant browser microphone permission
Check if HTTPS or localhost (WebRTC requires secure context)
Verify GOOGLE_GENERATIVE_AI_API_KEY is set
Try fallback: Voice should work with Web Speech API if Gemini fails

Image analysis fails

Symptoms: Uploading images shows error or no response.Solution:

Check image size (max 10MB by default)
Verify GOOGLE_GENERATIVE_AI_API_KEY is set
Check supported formats: JPEG, PNG, WebP
Check Gemini quota at AI Studio

Port 3000 already in use

Symptoms:

Error: Port 3000 is already in use

Solution: Use a different port:

PORT=3001 npm run dev

Or kill the process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

TypeScript errors in IDE

Symptoms: Red squiggly lines in VS Code but code runs fine.Solution:

Restart TypeScript server in VS Code:
- Cmd/Ctrl + Shift + P
- “TypeScript: Restart TS Server”
Ensure you opened the project root (not a parent folder)
Check .vscode/settings.json for TypeScript config

Build fails but dev works

Symptoms: npm run dev works but npm run build fails.Solution:

Run type-check to find issues:
```
npm run type-check
```
Fix any TypeScript errors
Check for environment variables used in build (must be set)
Clear Next.js cache:
```
rm -rf .next
npm run build
```

Development Workflow

Recommended workflow for contributing to GIMA:

Setup Git Hooks

Husky automatically installs Git hooks for:

Pre-commit: Lints and formats staged files
Commit-msg: Validates commit message format

npm run prepare

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes

Write code
Add tests in tests/ directory
Update documentation if needed

Run Quality Checks

# Lint and format
npm run lint:fix
npm run format

# Type check
npm run type-check

# Run tests
npm test

Commit with Conventional Commits

git add .
git commit -m "feat: add new feature"

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Push and Create PR

git push origin feature/your-feature-name

Then create a Pull Request on GitHub.

Commit Message Format: type(scope): descriptionExamples:

feat(chat): add message reactions
fix(voice): resolve transcription timeout
docs(readme): update installation steps

Next Steps

Now that you have GIMA installed:

Configuration Guide

Learn about advanced configuration options

Core Features

Explore multimodal chat capabilities

AI Tools

Discover AI-powered maintenance tools

Architecture

Understand the system architecture

Getting Help

If you encounter issues not covered here:

GitHub Issues

Report bugs or request features

View Source Code

Browse the full source code

Get Started

Core Features

AI Tools

Guides

Architecture

System Requirements

Node.js

Package Manager

Installation Methods

Install with npm

Install with Yarn

Install with pnpm

Environment Variables

Required Variables

Optional Variables

Feature Flags

Complete .env.local Example

Key Technologies

Next.js 16

React 19

Vercel AI SDK v5

Tailwind CSS 4

TypeScript 5

Zod 4

Available Scripts

Project Structure

Verification Steps

Troubleshooting

Development Workflow

Next Steps

Configuration Guide

Core Features

AI Tools

Architecture

Getting Help

GitHub Issues

View Source Code

Build docs developers (and LLMs) love

Get Started

Core Features

AI Tools

Guides

Architecture

​System Requirements

Node.js

Package Manager

​Installation Methods

​Install with npm

​Install with Yarn

​Install with pnpm

​Environment Variables

​Required Variables

​Optional Variables

​Feature Flags

​Complete .env.local Example

​Key Technologies

Next.js 16

React 19

Vercel AI SDK v5

Tailwind CSS 4

TypeScript 5

Zod 4

​Available Scripts

​Project Structure

​Verification Steps

​Troubleshooting

​Development Workflow

​Next Steps

Configuration Guide

Core Features

AI Tools

Architecture

​Getting Help

GitHub Issues

View Source Code

Build docs developers (and LLMs) love

System Requirements

Installation Methods

Install with npm

Install with Yarn

Install with pnpm

Environment Variables

Required Variables

Optional Variables

Feature Flags

Complete .env.local Example

Key Technologies

Available Scripts

Project Structure

Verification Steps

Troubleshooting

Development Workflow

Next Steps

Getting Help