Chat Application Documentation¶

Welcome to the comprehensive documentation for our production-grade AI chat application.

🚀 Quick Links¶

📖 About This Project¶

This is a production-grade AI chat application built with:

• Next.js 15 with App Router and Turbopack
• React 19 with Server Components
• TypeScript 5 in strict mode
• Google Vertex AI (Gemini 2.5 models)
• Tailwind CSS 4 with shadcn/ui v4
• NextAuth.js for authentication

Key Features¶

✅ Real-time AI Chat - Streaming responses with multimodal support (text + images) ✅ Server-First Architecture - React Server Components by default ✅ Type-Safe - TypeScript strict mode + Zod runtime validation ✅ Secure - OAuth, rate limiting, input validation, security headers ✅ Production-Ready - Deployed on Google Cloud Run with CI/CD ✅ Well-Documented - Comprehensive docs, JSDoc, and code patterns

🏗️ Architecture Overview¶

graph TB
    Browser[Browser] --> NextJS[Next.js 15 App]
    NextJS --> Middleware[Middleware Layer]
    Middleware --> Auth[Authentication]
    Middleware --> RateLimit[Rate Limiting]
    Middleware --> Security[Security Headers]
    NextJS --> API[API Routes]
    API --> Services[Service Layer]
    Services --> VertexAI[Google Vertex AI]
    NextJS --> Components[React Components]
    Components --> UI[shadcn/ui]

    style VertexAI fill:#4285f4,color:#fff
    style NextJS fill:#000,color:#fff
    style Components fill:#61dafb,color:#000

Detailed Architecture

🎯 Getting Started Paths¶

For New Developers¶

1. Quick Start - 5-minute setup guide
2. Development Guide - Comprehensive setup
3. Editor Setup - VS Code/Zed configuration
4. Project Navigation - Find your way around

For Contributors¶

1. Contributing Guidelines - How to contribute
2. Code Patterns - Coding standards
3. Common Mistakes - Avoid pitfalls
4. Testing Guide - Test structure

For DevOps/Deployment¶

1. Deployment Overview - Getting started
2. Cloud Run Deployment - Step-by-step
3. GitHub Actions - CI/CD setup
4. Security - Security practices

📚 Documentation Structure¶

docs/
├── guides/               # How-to guides and tutorials
├── adr/                  # Architecture Decision Records
├── deployment/           # Deployment guides
├── security/             # Security documentation
├── features/             # Feature-specific docs
└── .github/patterns/     # Code patterns and examples

🔑 Key Concepts¶

Server Components vs Client Components¶

This app uses React Server Components (RSC) by default:

• ✅ Server Components - Default, no "use client" needed
• 🔵 Client Components - Add "use client" when you need interactivity

Server Component Pattern

Service Layer Pattern¶

Business logic lives in dedicated service classes:

export class ChatService {
  async streamChat(messages: Message[]): Promise<ReadableStream> {
    // Business logic here
  }
}

Service Layer Pattern

Input Validation¶

All external data is validated with Zod schemas:

const schema = z.object({
  messages: z.array(messageSchema),
  model: z.string().optional(),
});

const validated = schema.parse(body);

Validation Pattern

🛡️ Security¶

Security is built-in with multiple layers:

1. Security Headers - CSP, HSTS, X-Frame-Options
2. Rate Limiting - 5 requests / 10 seconds per IP
3. Authentication - Google OAuth + email allowlist
4. Input Validation - Zod schemas for all inputs
5. Secure Secrets - Google Secret Manager

Security Documentation

🚀 Tech Stack¶

📊 Project Status¶

• Production: chat.daza.ar
• Repository: github.com/roofsonfire/chat
• Status: ✅ Active development
• License: MIT

Detailed Project Status

🤝 Contributing¶

We welcome contributions! Please see our Contributing Guidelines.

Quick Contribution Steps¶

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests
5. Submit a pull request

Full Contributing Guide

📝 Documentation Standards¶

This documentation follows these principles:

• Searchable - Full-text search enabled
• Visual - Diagrams and screenshots where helpful
• Practical - Real code examples
• Up-to-date - Maintained with the codebase
• AI-friendly - Optimized for GitHub Copilot context

Documentation Guidelines

🔗 External Resources¶

• Next.js 15 Documentation
• React 19 Documentation
• shadcn/ui Components
• Google Vertex AI Documentation
• Tailwind CSS Documentation

Last Updated: November 2025 Maintained by: Core Development Team Questions? Open an issue on GitHub