🎓 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

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

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

🚀 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

Clone the repository

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

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

Start the application

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

# Check if all services are running
docker-compose ps

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)

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

Register an account at http://localhost:8081/register
Login with your credentials
Upload a university document (PDF format)
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

Read the guidelines
- Check AGENTS.md for development guidelines and best practices

Fork the repository

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

Create a feature branch

git checkout -b feature/your-feature-name

Make your changes
- Follow the existing code style
- Write tests for new features
- Update documentation as needed
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

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

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🎓 AdmissionAgent

AI-Powered University Admission Assistant with RAG Technology

📖 Overview

🚀 Built with Golang for Performance

Why AdmissionAgent?

✨ Features

Core Capabilities

Technical Features

🛠️ Tech Stack

Backend

AI & ML

Frontend

Infrastructure

🏗️ Architecture

High-Level System Design

RAG Pipeline Flow

Document Processing Pipeline

🚀 Quick Start

Prerequisites

Installation Steps

Verify Installation

First Steps

📁 Project Structure

🔧 Development

Running Locally (Without Docker)

Running Tests

Database Migrations

Code Quality

🤝 Contributing

Contribution Workflow

Development Guidelines

Areas for Contribution

📜 License

🙏 Acknowledgments

📞 Contact & Support

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🎓 AdmissionAgent

AI-Powered University Admission Assistant with RAG Technology

📖 Overview

🚀 Built with Golang for Performance

Why AdmissionAgent?

✨ Features

Core Capabilities

Technical Features

🛠️ Tech Stack

Backend

AI & ML

Frontend

Infrastructure

🏗️ Architecture

High-Level System Design

RAG Pipeline Flow

Document Processing Pipeline

🚀 Quick Start

Prerequisites

Installation Steps

Verify Installation

First Steps

📁 Project Structure

🔧 Development

Running Locally (Without Docker)

Running Tests

Database Migrations

Code Quality

🤝 Contributing

Contribution Workflow

Development Guidelines

Areas for Contribution

📜 License

🙏 Acknowledgments

📞 Contact & Support