GitHub Repo Analyzer

A production-grade, enterprise-ready SaaS application for authenticating with GitHub, exploring repositories, importing workspace metadata, and preparing codebases for AI-powered analysis.

---

🌟 Architecture Overview

The system follows a clean, modular architecture separating the frontend, backend API, shared type contracts, and infrastructure orchestration.

githubAI/
├── frontend/                 # Next.js 16 (App Router), React 20, Tailwind CSS v4, React Query
├── backend/                  # NestJS TypeScript API, Prisma ORM, Auth, GitHub REST v3
├── packages/
│   └── shared/               # Shared TypeScript DTOs and API contracts
├── docker/                   # Docker Compose & container definitions
├── docs/                     # Swagger & REST API Documentation
├── README.md
└── .env.example

githubAI/
├── frontend/                 # Next.js 16 App Router, React 20, Tailwind v4, Lucide, React Query
│   ├── src/
│   │   ├── app/              # App Router Pages: Landing (/), Login (/login), Dashboard (/dashboard), Repositories (/repositories), Settings (/settings), Profile (/profile), 404 (/not-found)
│   │   ├── components/       # UI Library: Navbar, Sidebar, Breadcrumb, Card, Table, Dialog, Skeleton, EmptyState, LoadingSpinner, Pagination, SearchBar, Toast
│   │   ├── context/          # React Auth Context (JWT session handling & OAuth triggers)
│   │   ├── lib/              # Axios API Client with interceptors & automatic bearer token attachment
│   │   └── styles/           # Tailwind CSS v4 & custom glassmorphism design tokens
│   ├── Dockerfile
│   └── package.json
├── backend/                  # NestJS TypeScript API Server
│   ├── src/
│   │   ├── modules/
│   │   │   ├── auth/         # OAuth callback, CryptoService (AES-256-GCM), Passport JWT Strategy, Guards
│   │   │   ├── github/       # GitHub REST v3 service with retry logic, rate limit handling, DTOs
│   │   │   ├── repository/   # Repository import service, deduplication, search/filter/sort, dashboard stats
│   │   │   ├── user/         # User profile service & controller
│   │   │   ├── health/       # PostgreSQL & Redis readiness checks
│   │   │   ├── database/     # PrismaService connection manager
│   │   │   ├── config/       # Environment validation via Zod
│   │   │   └── logger/       # Structured Request & Performance Logger
│   │   ├── common/           # Transform Interceptor, Exception Filter, Logging Interceptor, CurrentUser Decorator
│   │   ├── app.module.ts
│   │   └── main.ts           # Helmet, CORS, Swagger, CookieParser setup
│   ├── prisma/
│   │   └── schema.prisma     # Prisma PostgreSQL schema (User & Repository models)
│   ├── Dockerfile
│   └── package.json
├── packages/
│   └── shared/               # Shared TypeScript DTOs, Enums, and ApiResponse wrappers
├── docker/
│   └── docker-compose.yml    # PostgreSQL 16, Redis 7, Backend API, Frontend App orchestration
├── docs/
│   ├── api.md                # Complete REST API reference
│   └── swagger.md            # OpenAPI Swagger setup guide
├── .eslintrc.js
├── .prettierrc
├── .gitignore
└── README.md

---

🚀 Tech Stack

Frontend

• Framework: Next.js 16 (App Router)
• UI Library: React 20, Lucide Icons, Custom Glassmorphism styling
• Styling: Tailwind CSS v4 + Vanilla CSS Design System Variables
• State & Query Management: TanStack React Query v5, Context API
• Form & Validation: React Hook Form, Zod

Backend

• Framework: NestJS (TypeScript)
• Database: PostgreSQL 16 via Prisma ORM
• Cache & Rate Limiting: Redis 7, NestJS Throttler
• Security: AES-256-GCM Token Encryption, Passport JWT, Helmet, CORS, Cookie Parser
• Integrations: GitHub REST API v3 (Octokit/Axios with exponential backoff & rate limit handling)

---

🔒 Security Highlights

1. AES-256-GCM Encrypted Tokens: GitHub OAuth tokens are encrypted before being saved in PostgreSQL.
2. HttpOnly Refresh Cookies + JWT: JWT access tokens for API requests coupled with secure HTTP-only cookies.
3. Throttler & Helmet Protection: Built-in protection against brute-force attacks and security header vulnerabilities.

---

⚙️ Quick Start (Local Development)

Prerequisites

• Node.js >= 20.x
• Docker & Docker Compose
• PostgreSQL 16 & Redis 7 (or running via Docker Compose)

1. Clone & Install Dependencies

# Install backend dependencies
cd backend
npm install

# Install frontend dependencies
cd ../frontend
npm install

2. Environment Configuration

Copy the sample environment configuration:

cp .env.example backend/.env
cp frontend/.env.example frontend/.env.local

3. Database Migration & Prisma Client

cd backend
npx prisma generate
npx prisma migrate dev --name init

4. Run Development Servers

Run Backend:

cd backend
npm run start:dev
# Server starts on http://localhost:4000/api
# Swagger API docs on http://localhost:4000/api/docs

Run Frontend:

cd frontend
npm run dev
# Frontend app starts on http://localhost:3000

---

🐳 Docker Deployment

To launch the full production stack using Docker Compose (PostgreSQL, Redis, NestJS Backend, Next.js Frontend):

cd docker
docker-compose up --build -d

Service URLs:

• Frontend App: http://localhost:3000
• Backend REST API: http://localhost:4000/api
• Swagger Documentation: http://localhost:4000/api/docs
• PostgreSQL: localhost:5432
• Redis: localhost:6379

---

🧪 Testing

Execute unit and integration test suites:

cd backend
npm run test

---

🔮 Future AI Integration Architecture (Phase 2 Readiness)

The Phase 1 codebase has been designed to allow future AI modules to plug in without architectural refactoring:

• Vector Database (Qdrant): Can connect directly to the existing Repository model via a new embeddings microservice.
• Tree-sitter AST Parser: Can be injected as a background task processor (Kafka / BullMQ) consuming imported repository events.
• LLM Chat & RAG: NestJS service modules can utilize the encrypted accessToken stored per user to clone code for prompt context enrichment.

The Phase 2

---

📄 License

UNLICENSED. Production-Grade Enterprise Codebase.

GithubAI