🎓 AdmissionAgent

AI-Powered University Admission Assistant with RAG Technology

Helping students discover their perfect university match through intelligent conversation

Features • Quick Start • Architecture • Tech Stack • Contributing

---

📖 Overview

AdmissionAgent is a production-ready RAG (Retrieval-Augmented Generation) chatbot built with Golang that helps students navigate university admissions. Unlike typical Python-based RAG systems, this project demonstrates high-performance AI applications in Go, leveraging LangChain Go, pgvector, and Neo4j for intelligent document retrieval and conversational AI.

🚀 Built with Golang for Performance

While most RAG systems are built with Python, AdmissionAgent showcases Go's capabilities for AI/ML applications:

• ⚡ High concurrency - Handle thousands of concurrent chat sessions
• 🔥 Low latency - Sub-second response times with efficient vector search
• 📦 Single binary deployment - No dependency hell, just compile and run
• 🛡️ Type safety - Catch errors at compile time, not runtime
• 🏗️ Clean architecture - Hexagonal design with clear separation of concerns

Why AdmissionAgent?

• 🎯 Personalized Recommendations - Get university suggestions tailored to your profile
• 💬 Natural Conversations - Chat naturally about your admission concerns
• 📚 Knowledge-Backed Answers - Responses grounded in real university data
• 🔍 Smart Search - Vector-based semantic search across university documents
• 🚀 Real-time Processing - Instant responses with async document processing

---

✨ Features

Core Capabilities

• 🤖 AI-Powered Chat Interface - Natural language conversations with context awareness
• 📄 Document Processing - Automatic PDF parsing, chunking, and embedding
• 🔎 Semantic Search - Vector similarity search using pgvector (3072-dim embeddings)
• 👤 User Authentication - Secure JWT-based authentication system
• 💾 Conversation History - Persistent chat sessions with Redis caching
• 📊 Knowledge Graph - Neo4j-powered relationship mapping between universities
• ⚡ Async Processing - Background workers for document indexing via Redis Streams

Technical Features

• 🏗️ Hexagonal Architecture - Clean separation of concerns with ports & adapters
• 🔄 RESTful API - Well-structured backend API with Gin framework
• 🎨 Modern Frontend - Responsive Vue 3 interface with Vite
• 🐳 Containerized - Full Docker Compose setup for easy deployment
• 📈 Scalable - Microservices-ready architecture with worker pools

---

🛠️ Tech Stack

Backend

Technology	Purpose	Version
Go	Backend language	1.24.6
Gin	HTTP web framework	1.11.0
PostgreSQL	Primary database	17
pgvector	Vector similarity search	Latest
Redis	Caching & message broker	7.0
Neo4j	Graph database	5.26.0
MinIO	Object storage (S3-compatible)	Latest

AI & ML

Technology	Purpose
LangChain Go	LLM orchestration framework
Gemini AI	Embedding model (gemini-embedding-001)
Vector Embeddings	3072-dimensional semantic search

Frontend

Technology	Purpose	Version
Vue 3	Frontend framework	3.5.24
Vite	Build tool & dev server	7.2.4
Vue Router	Client-side routing	4.6.4
Axios	HTTP client	1.13.2

Infrastructure

• Docker & Docker Compose - Containerization and orchestration
• Air - Live reload for Go development
• golang-migrate - Database migration management

---

🏗️ Architecture

High-Level System Design

graph TB
    subgraph "Client Layer"
        UI[Vue 3 Frontend]
    end
    
    subgraph "API Layer"
        API[Gin REST API]
        Auth[JWT Authentication]
    end
    
    subgraph "Application Layer"
        Chat[Chat Service]
        RAG[RAG Pipeline]
        Upload[Document Upload]
    end
    
    subgraph "AI Services"
        Embed[Embedding Service<br/>Gemini AI]
        LLM[LLM Service<br/>LangChain]
    end
    
    subgraph "Data Layer"
        PG[(PostgreSQL<br/>+ pgvector)]
        Redis[(Redis<br/>Cache & Queue)]
        Neo4j[(Neo4j<br/>Knowledge Graph)]
        MinIO[(MinIO<br/>Object Storage)]
    end
    
    subgraph "Background Processing"
        Worker[Document Worker]
        Indexer[Vector Indexer]
    end
    
    UI --> API
    API --> Auth
    API --> Chat
    API --> Upload
    
    Chat --> RAG
    Chat --> Redis
    
    RAG --> Embed
    RAG --> LLM
    RAG --> PG
    
    Upload --> MinIO
    MinIO --> Worker
    Worker --> Indexer
    Indexer --> Embed
    Indexer --> PG
    Indexer --> Neo4j
    
    style UI fill:#4FC08D
    style API fill:#00ADD8
    style RAG fill:#FF6B6B
    style PG fill:#336791
    style Redis fill:#DC382D
    style Neo4j fill:#008CC1

Loading

RAG Pipeline Flow

sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant RAG
    participant Vector DB
    participant LLM
    
    User->>Frontend: Ask question
    Frontend->>API: POST /chat/message
    API->>RAG: Process query
    RAG->>Vector DB: Semantic search
    Vector DB-->>RAG: Relevant documents
    RAG->>LLM: Generate response with context
    LLM-->>RAG: AI-generated answer
    RAG-->>API: Response
    API-->>Frontend: JSON response
    Frontend-->>User: Display answer

Loading

Document Processing Pipeline

graph LR
    A[Upload PDF] --> B[MinIO Storage]
    B --> C[Redis Stream Event]
    C --> D[Worker Picks Up]
    D --> E[Extract Text]
    E --> F[Chunk Text]
    F --> G[Generate Embeddings]
    G --> H[Store in pgvector]
    G --> I[Build Knowledge Graph]
    I --> J[Neo4j]
    
    style A fill:#4FC08D
    style B fill:#C72E49
    style D fill:#00ADD8
    style H fill:#336791
    style J fill:#008CC1

Loading

---

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

• Docker (v20.10+) and Docker Compose (v2.0+)
• Git for cloning the repository
• Gemini API Key (get it from Google AI Studio)

Installation Steps

1. Clone the repository

git clone http://github.com/bienwithcode/AdmissionAgent.git
cd AdmissionAgent

2. Configure environment variables

# Copy the example environment file
cp .env.example .env

# Edit .env and add your Gemini API key
# Required variables:
# - GEMINI_API_KEY=your_api_key_here
# - MINIO_ROOT_USER=minioadmin
# - MINIO_ROOT_PASSWORD=minioadmin
# - S3_BUCKET=documents

3. Start the application

# Start all services (backend, frontend, databases, workers)
docker-compose up -d

# Check if all services are running
docker-compose ps

4. Access the application

• Frontend: http://localhost:8081
• Backend API: http://localhost:8080
• MinIO Console: http://localhost:9001 (minioadmin/minioadmin)
• Neo4j Browser: http://localhost:7474 (neo4j/password)

5. Initialize the database

# Run database migrations
docker-compose exec backend /scripts/migrate.sh up

Verify Installation

# Check backend health
curl http://localhost:8080/health

# Check if worker is processing
docker-compose logs -f worker

First Steps

1. Register an account at http://localhost:8081/register
2. Login with your credentials
3. Upload a university document (PDF format)
4. Start chatting about university admissions!

---

📁 Project Structure

AdmissionAgent/
├── cmd/                    # Application entry points
│   ├── api/               # REST API server
│   └── worker/            # Background worker
├── internal/              # Private application code
│   ├── adapters/         # External adapters (DB, APIs)
│   ├── core/             # Business logic & domain models
│   ├── ports/            # Interface definitions
│   └── services/         # Application services
├── pkg/                   # Public libraries
├── ui/                    # Vue 3 frontend
│   ├── src/
│   │   ├── components/   # Vue components
│   │   ├── views/        # Page views
│   │   └── router/       # Vue Router config
│   └── public/           # Static assets
├── scripts/               # Utility scripts
├── docker-compose.yml     # Docker orchestration
├── .env.example          # Environment template
├── AGENTS.md             # AI agent guidelines
└── README.md             # This file

---

🔧 Development

Running Locally (Without Docker)

Backend:

# Install dependencies
go mod download

# Run with hot reload
air

# Or run directly
go run cmd/api/main.go

Frontend:

cd ui
npm install
npm run dev

Running Tests

# Run all tests
go test ./...

# Run with coverage
go test -cover ./...

# Run specific package tests
go test ./internal/core/...

Database Migrations

# Create a new migration
migrate create -ext sql -dir migrations -seq create_users_table

# Run migrations
docker-compose exec backend /scripts/migrate.sh up

# Rollback migrations
docker-compose exec backend /scripts/migrate.sh down 1

Code Quality

# Format code
go fmt ./...

# Run linter
golangci-lint run

# Vet code
go vet ./...

---

🤝 Contributing

We welcome contributions from the community! Here's how you can help:

Contribution Workflow

1. Read the guidelines

   • Check AGENTS.md for development guidelines and best practices

2. Fork the repository

   git clone http://github.com/YOUR_USERNAME/AdmissionAgent.git

3. Create a feature branch

   git checkout -b feature/your-feature-name

4. Make your changes

   • Follow the existing code style
   • Write tests for new features
   • Update documentation as needed

5. Commit your changes

   git commit -m "feat: add amazing feature"

   Follow Conventional Commits:

   • feat: - New features
   • fix: - Bug fixes
   • docs: - Documentation changes
   • refactor: - Code refactoring
   • test: - Test additions/changes

6. Push and create a Pull Request

   git push origin feature/your-feature-name

Development Guidelines

• Architecture: Follow hexagonal architecture principles
• Testing: Maintain test coverage above 70%
• Documentation: Update documentation for new features
• Code Style: Use gofmt and follow Go best practices
• Commits: Write clear, descriptive commit messages

Areas for Contribution

• 🐛 Bug Fixes - Check the Issues page
• ✨ New Features - Propose features via GitHub Discussions
• 📚 Documentation - Improve README, add tutorials, write guides
• 🧪 Testing - Increase test coverage
• 🎨 UI/UX - Enhance the frontend interface
• 🌐 Internationalization - Add multi-language support

---

📜 License

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

---

🙏 Acknowledgments

• LangChain - For the excellent LLM orchestration framework
• Google Gemini - For powerful embedding models
• pgvector - For efficient vector similarity search
• Neo4j - For graph database capabilities
• Vue.js Team - For the amazing frontend framework

---

📞 Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

⭐ Star this repository if you find it helpful!

Made with ❤️ by bienwithcode