NodeHunt_2026 Backend

This is the FastAPI backend for the SIAM-VIT 2025 NodeHunt.

What is happening now?

This backend serves as the core logic for the NodeHunt scavenger hunt. It manages the nodes (riddles/questions), validates team passcodes, tracks team progress, and provides an admin dashboard. The application connects to a PostgreSQL database using asynchronous SQLAlchemy and asyncpg to store team data and logs.

How questions are linked

The scavenger hunt is structured as a directed graph of nodes. The logic for this graph is stored centrally in data/nodes_config.py.

• Nodes: Each node has 2 sets of questions (Set 1 and Set 2).
• Routes: When a team submits a passcode at a node, the backend checks the routes dictionary for that node. The passcode maps to a target node (e.g., submitting pogu2 at Node 1 redirects to Node 2).
• Conditional Routes: Some routes are conditional and require the team to have followed an exact path of previous nodes to be valid (e.g., Node 8 has a target that requires the path [1, 3, 5, 8]).
• Special Routes: Passcodes can also lead to __winner__ (the team successfully completed the hunt) or __out__ (the team is eliminated). Since all passcode verification and routing logic is stored server-side, participants cannot inspect the frontend code to cheat and find the next nodes.

How to use this with pgAdmin (Database Setup)

To run this project locally, you need a PostgreSQL database. You can manage this easily using pgAdmin.

1. Install PostgreSQL and pgAdmin: If you haven't already, download and install PostgreSQL. pgAdmin usually comes bundled with it.
2. Create a Database in pgAdmin:
   • Open pgAdmin and connect to your local PostgreSQL server (default port is 5432).
   • Right-click on Databases -> Create -> Database...
   • Name the database NodeHunt (or any name you prefer) and save.
3. Configure Environment Variables:
   • Copy the .env.example file to a new file named .env in this backend folder.
   • Update the DATABASE_URL in .env to match your PostgreSQL credentials.
   • Format: postgresql+asyncpg://<username>:<password>@localhost:5432/<database_name>
   • Example: DATABASE_URL=postgresql+asyncpg://postgres:mysecretpassword@localhost:5432/NodeHunt
4. Run the Application:
   • When you start the application (uvicorn main:app --reload), the backend will automatically connect to this database.
   • The create_tables() function in database.py will automatically create the necessary tables in your NodeHunt database on startup. You can view these newly created tables in pgAdmin under Schemas -> public -> Tables.