StellarStack Gemini AI Chat Template

A production-ready MERN stack template for building AI-powered chat applications, developed with ❤️ by Team StellarStackLtd For Nexlayer Community. This template provides a robust foundation for creating interactive chat experiences using Google's Gemini Pro API, featuring modern authentication, real-time chat capabilities, and scalable architecture.

🚀 Quick Start: From Zero to Production in 15 Minutes

Welcome! You're about to deploy your very own AI-powered chat application to the Nexlayer. By the end of this tutorial, you'll have a live website that anyone can visit and chat with AI.

What You're Building

Your app will have three awesome features:

Smart AI Chat - Users can have conversations with Google's Gemini AI
Google Login - Secure authentication so users can save their chat history
Live on the Internet - Anyone can visit your custom URL and use your app

Before We Start

You'll need:

A GitHub account (free)
15 minutes of your time
Zero experience with cloud deployment (we'll teach you everything!)

Step 1: Get Your Free Google API Keys (5 minutes)

🤖 Get Your Google Gemini AI Key

Visit Google AI Studio
Sign in with your Google account
Click "Create API Key" - it's the big blue button
Copy your key - it starts with AIza...

🔐 Get Your Google OAuth Keys

Visit Google Cloud Console
Create a new project: Click "Select a project" → "New Project"
Enable OAuth: Go to "APIs & Services" → "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
Set up redirect URIs:
- http://localhost:3030/auth/google/callback
- https://YOUR-APP-NAME.nexlayer.io/auth/google/callback
Save your Client ID and Client Secret

Step 2: Fork the Code (2 minutes)

Visit the template: Stellar-Ai-Chat-MERN-Template
Click "Fork" in the top-right corner
Choose your account as the destination

Step 3: Configure Your App (3 minutes)

Clone your fork: git clone https://github.com/YOUR-USERNAME/Stellar-Ai-Chat-MERN-Template.git
Open nexlayer.yaml and replace placeholder values with your real API keys
Choose your unique app name (becomes part of your website URL)

Step 4: Set Up Automatic Deployment (3 minutes)

Create a GitHub Personal Access Token with write:packages and read:packages permissions
Add the token to your repository secrets as GHCR_TOKEN_RW
Enable "Read and write permissions" in Actions settings

Step 5: Deploy to Production (2 minutes)

Push your changes: git add . && git commit -m "Configure deployment" && git push
Watch the magic happen in GitHub Actions
Your app is live at: https://YOUR-APP-NAME.nexlayer.io

🎉 Congratulations! You've just deployed a production-ready AI application to the cloud!

📁 Recommended Project Structure

project/
├── client-fe/          # Frontend React app
├── server/             # Backend Express app
├── nexlayer.yaml       # Main deployment config
├── docker-compose.yml  # Local development
└── .github/workflows/
    └── build_and_deploy.yml       # CI/CD build and deploy to nexlayer pipeline
    └── ci.yml        # CI/CD pipeline

🔧 Key Configuration Patterns

Multi-service apps: Separate containers for frontend/backend
Database setup: Use platform images with init scripts
Environment management: Pod-level variable scoping
Routing: Avoid path conflicts between services

🧠 Knowledge Sharing Opportunities

Template Complexity: This represents advanced use case vs. Hello World
Scalability Patterns: Multi-pod deployments with proper service communication
DevOps Integration: Full CI/CD with image building and deployment automation
Security Best Practices: Secret management and access control patterns

Description

StellarStack AI Chat Template is a comprehensive solution for building AI chat applications, providing:

User Authentication:
- Google OAuth V2 integration
- Role-based access control
- Secure session management
Chat Features:
- AI-powered conversations using Google Gemini Pro
- Rate limiting for non-authenticated users
- Unlimited access for authenticated users
- Chat history management
Modern Architecture:
- MERN Stack (MongoDB, Express.js, React.js, Node.js)
- Redux Toolkit for state management
- Docker containerization
- Scalable microservices architecture

🗺️ Architecture Overview

This structure shows you how Nexlayer organizes your application into distinct, manageable pieces. Each pod has its own responsibility and configuration, but they all work together as one cohesive app.

How Your Stack Connects Automatically

Here's the magic of Nexlayer - all these services discover and connect to each other automatically. This diagram shows exactly how data flows through your application:

💻 System Requirements

Minimum Requirements

Node.js: 18.x or higher
npm: 8.x or higher
MongoDB: 6.0 or higher (local or Atlas)
Git: 2.x or higher

Browser Support

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

🛠️ Installation

Prerequisites

Node.js (v18 or higher)
MongoDB (local or Atlas)
Docker (optional)
Google Cloud Console account (for OAuth and Gemini API)

Quick Installation

# Clone the repository
git clone https://github.com/StellarStack/Stellar-Ai-Chat-MERN-Template.git
cd Stellar-Ai-Chat-MERN-Template

# Install dependencies
cd server && npm install
cd ../client-fe && npm install

# Set up environment variables
cp server/.env.example server/.env
cp client-fe/.env.example client-fe/.env

# Edit the .env files with your configuration
# See ENVIRONMENT_SETUP.md for detailed instructions

⚙️ Configuration

Environment Variables

The application uses environment variables for configuration. See ENVIRONMENT_SETUP.md for detailed setup instructions.

Key Configuration Files

nexlayer.yaml - Production deployment configuration
docker-compose.yml - Local development with Docker
server/.env - Backend environment variables
client-fe/.env - Frontend environment variables

🚀 Development

Local Development

# Start the backend server
cd server
npm run dev

# In a new terminal, start the frontend
cd client-fe
npm start

Docker Development

# Start all services with Docker Compose
docker-compose up --build

# Stop all services
docker-compose down

Development Scripts

Backend (server/)

npm run dev      # Start development server with nodemon
npm run build    # Build for production
npm test         # Run tests
npm run lint     # Run ESLint
npm run format   # Format code with Prettier

Frontend (client-fe/)

npm start        # Start development server
npm run build    # Build for production
npm test         # Run tests
npm run lint     # Run ESLint
npm run format   # Format code with Prettier

🧪 Testing

Running Tests

# Backend tests
cd server
npm test

# Frontend tests
cd client-fe
npm test

# Run all tests
npm run test:all

Test Coverage

The project includes comprehensive test coverage for both frontend and backend components.

CI/CD Testing

GitHub Actions automatically runs tests on every push and pull request:

Unit tests for both frontend and backend
Integration tests
Build verification
Code quality checks

🚀 Deployment

Nexlayer Deployment (Recommended)

The template is optimized for deployment on Nexlayer with automatic CI/CD:

Fork the repository
Configure environment variables in nexlayer.yaml
Set up GitHub secrets for automated deployment
Push to main branch - automatic deployment triggers

Manual Deployment

# Build Docker images
docker build -t your-app-backend ./server
docker build -t your-app-frontend ./client-fe

# Deploy to your preferred platform
# See platform-specific documentation

Deployment Options

Nexlayer (recommended) - Optimized for this template
Heroku - Easy deployment with Git integration
AWS - Scalable cloud infrastructure
Google Cloud - Enterprise-grade hosting
Vercel - Frontend deployment
Railway - Full-stack deployment

📚 API Documentation

Backend API Endpoints

Authentication

POST /v1/auth/google - Google OAuth authentication
POST /v1/auth/refresh - Refresh access token
GET /v1/auth/logout - User logout

Chat

POST /v1/gemini/api/chat - Send message to AI
GET /v1/gemini/api/getchathistory - Get user's chat history
POST /v1/gemini/api/chatdata - Get specific chat data

User Management

POST /v1/user/location - Update user location
GET /v1/user/profile - Get user profile

Frontend API Integration

The frontend uses Redux Toolkit for state management and API calls. See the store files in client-fe/src/store/ for implementation details.

🔑 API Keys Required

1. Google OAuth

Google Cloud Console: https://console.cloud.google.com/
Create OAuth 2.0 credentials
Add authorized redirect URIs

2. Gemini AI

Google AI Studio: https://makersuite.google.com/app/apikey
Generate API key for Gemini models

3. MongoDB Atlas

MongoDB Atlas: https://cloud.mongodb.com/
Create cluster and database user
Get connection string

4. IP Geolocation

IP Geolocation API: https://ipgeolocation.io/
Sign up for API key

5. Geocoding

Geocode API: https://geocode.maps.co/
Get API key for reverse geocoding

🔒 Security Best Practices

✅ Do's

Use .env.example files as templates
Keep .env files in .gitignore
Use strong, unique secrets for JWT
Rotate API keys regularly
Use environment-specific configurations

❌ Don'ts

Never commit .env files to version control
Don't share API keys publicly
Don't use default/weak secrets
Don't hardcode values in source code

🐳 Docker & GitHub Container Registry

GitHub CR Steps

Create GitHub PAT with package-write rights:

docker login ghcr.io -u <github-username> -p <PAT-GithubWritePrivileges>

Build and push backend:

cd <repo-dir>
docker build -t stellar-gemini-ai-chatapp-backend:v0.1 -f ./server/Dockerfile ./server
docker tag stellar-gemini-ai-chatapp-backend:v0.1 ghcr.io/stellarstack/stellar-gemini-ai-chatapp-backend:v0.1
docker push ghcr.io/stellarstack/stellar-gemini-ai-chatapp-backend:v0.1

Build and push frontend:

docker build -t stellar-gemini-ai-chatapp-frontend:v0.1 -f ./client-fe/Dockerfile ./client-fe
docker tag stellar-gemini-ai-chatapp-frontend:v0.1 ghcr.io/stellarstack/stellar-gemini-ai-chatapp-frontend:v0.1
docker push ghcr.io/stellarstack/stellar-gemini-ai-chatapp-frontend:v0.1

🔧 Troubleshooting Common Issues

"Permission Denied" Error

Double-check your GHCR_TOKEN_RW secret is set correctly
Make sure you enabled "Read and write permissions" in Actions settings

"OAuth Redirect Mismatch"

Go back to Google Cloud Console
Add your exact Nexlayer URL to the authorized redirect URIs
Make sure there are no typos in your app name

"API Key Invalid"

Double-check your Gemini API key in nexlayer.yaml
Make sure you copied the entire key without extra spaces
Verify the key works by testing it in Google AI Studio

"Build Failed"

Check that both server/ and client-fe/ folders have package.json files
Make sure you ran npm install in both directories
Look at the GitHub Actions logs for specific error messages

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: npm test
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow the existing code style
Write tests for new features
Update documentation as needed
Ensure all tests pass before submitting

Issue Templates

We provide issue templates for:

📖 Documentation

Environment Setup Guide - Detailed environment configuration
Contributing Guidelines - How to contribute to the project
Code of Conduct - Community guidelines
Changelog - Version history and updates
Privacy Policy - Privacy and data handling
Disclaimer - Legal disclaimers

Features

🔐 Secure Authentication
🤖 AI-Powered Chat
📱 Responsive Design
🔄 Real-time Updates
📊 Analytics Integration
🌐 Location Services
🐳 Docker Support
🔍 Advanced Search
📝 Chat History
⚡ Performance Optimized
🧪 Comprehensive Testing
🔄 CI/CD Pipeline
📚 API Documentation
🌍 Multi-environment Support

🚀 Next Steps

Now that your app is live, here are some exciting directions to explore:

Learn More About the Stack

React (Frontend): Build interactive user interfaces
Express.js (Backend): Create REST APIs
MongoDB (Database): Store and query data efficiently

Expand Your App

Add more AI features (image generation, text-to-speech)
Improve user experience (real-time chat, push notifications)
Scale your app (caching, rate limiting, monitoring)

Deploy More Apps

Build a todo app with real-time collaboration
Create an e-commerce site with payments
Make a social media platform
Build a dashboard for data visualization

Documentation

For detailed documentation, visit our Nexlayer Docs.

Support

📄 License

This template is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Google Gemini AI for providing the AI capabilities
Nexlayer for the deployment platform
React and Express.js communities
All contributors and supporters of this project

Privacy & Legal

Built with ❤️ using the StellarStackLtd AI Chat Template

Name		Name	Last commit message	Last commit date
Latest commit History 85 Commits
.github		.github
.nexlayer		.nexlayer
client-fe		client-fe
server		server
.DS_Store		.DS_Store
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DISCLAIMER.md		DISCLAIMER.md
Dockerfile		Dockerfile
Dockerfile.bak		Dockerfile.bak
ENVIRONMENT_SETUP.md		ENVIRONMENT_SETUP.md
LICENSE		LICENSE
PRIVACY-POLICY.md		PRIVACY-POLICY.md
README.md		README.md
docker-compose.yaml		docker-compose.yaml
nexlayer.yaml		nexlayer.yaml
nexlayer.yaml.bak		nexlayer.yaml.bak

License

StellarStack/Stellar-Ai-Chat-MERN-Template

Folders and files

Latest commit

History

Repository files navigation