Welcome to the official starter repository for the
AI / API Preliminary Round of BUET CSE FEST Hackathon 2026.

This repository contains:

• The complete problem statement
• Database setup files
• External API specifications
• Testing tools
• Submission templates

You are expected to fork this repository and build your solution inside it.

Follow these steps in order.

Click Fork on GitHub and create your own copy.

Then clone it:

git clone <your-fork-url>
cd <repo-name>

Go to:

problem-statement/problem-statement.md

This file explains everything.

Start here.

You may use any backend framework or language.

Examples:

• Python (Flask / FastAPI / Django)
• Node.js (Express / NestJS)
• TypeScript
• Any other server framework

All your backend code must go inside:

backend/

Choose ONE method:

Follow:

problem-statement/run-postgres-with-docker.md

Follow:

problem-statement/run-postgres-locally.md

Inside backend/, create your server.

Your server must provide:

• GET /health
• POST /query

As described in the problem statement.

Open:

hackathon.yml

Edit it to match your backend.

Templates are available in:

hackathon.yml.templates/

Copy the closest template and modify it.

Example:

cp hackathon.yml.templates/hackathon.python.template.yml hackathon.yml

Inside backend/, create .env from .env.example:

cp .env.example .env

• Now fill up the env vars

DB_HOST=
DB_PORT=
DB_NAME=
DB_USER=
DB_PASSWORD=
GEMINI_API_KEY=

PORT=8080

Do NOT commit .env Put it in .gitingore.

Start your server using your commands.

Check:

curl http://localhost:8080/health

You should see:

{
  "status": "ok",
  "database": "connected"
}

Go to:

cd checker
python checker.py -b http://localhost:8080

Fix errors until tests pass.

.
├── backend/              ← Your server code goes here
│
├── checker/              ← Testing scripts
│
├── data/                 ← Database dump
│
├── external-apis/        ← API collections (Bruno)
│
├── hackathon.yml         ← Automation config (REQUIRED)
│
├── hackathon.yml.templates/ ← Ready-made templates
│
├── problem-statement/    ← Full documentation
│
└── README.md             ← You are reading this

Do not move or rename these folders.

External API definitions are provided in:

external-apis/

and

problem-statement/opeapi-specification.yml

Use these for tool selection.

Do NOT use other APIs.

Your project will be evaluated automatically.

The judge will:

1. Clone your repository
2. Read hackathon.yml
3. Generate .env
4. Install dependencies
5. Start your server
6. Call /health
7. Run checker

If any step fails, your submission may fail.

Read:

problem-statement/submission_guideline.md

Then submit your GitHub repository link via the Google Form.

❌ Writing code outside backend/ ❌ Missing hackathon.yml ❌ Committing .env ❌ Wrong server port ❌ Missing /health endpoint ❌ Hardcoding answers

Avoid these.

• Start simple
• First make /health work
• Then connect DB
• Then answer 1–2 queries
• Then add LLM
• Then add external APIs

Do not try to do everything at once.

If you are confused:

1. Re-read the problem statement
2. Check example templates
3. Just use chatGPT

Good luck, and happy hacking!