All the reading

Full-Stack

7 lessons, about 30 minutes. The check's questions come from these.

Choosing a weekend stack

1. Pick a weekend-sized stack

5 min

Key point

One rule

Pick the boring stack you can ship, debug, and explain. A weekend project is judged on whether it works and can be reviewed, not on how many tools you used.

Your stack must let you build a UI, call your own API route or backend, and store or handle the data your app needs.

Weekend-sized means small

A good hackathon stack has few moving parts. You should be able to run it locally, make one change, and understand where that change goes.

For many college projects, that means one full-stack framework, one styling choice, and one database or mock storage choice. Avoid adding mobile apps, queues, microservices, custom auth, and admin dashboards unless the problem truly needs them.

Your to-do

Use this filter

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Start with the feature you must demo in 2 minutes.
Choose tools at least one teammate has already used.
Prefer a stack with one command to run locally.
Check that hosting is possible on a free tier or a college-friendly plan.
Drop any tool you cannot explain in two sentences.

0 of 5 done

Example

Good stack choices

Here are weekend-sized options. Pick one, do not mix all of them.

If you already know another stack, use it. The point is to reduce risk.

Placing app state

2. Decide where state lives

4 min

Key point

One rule

Put state where it can survive as long as the user expects it to survive.

A dropdown can live in the UI. A logged-in user's tasks need the backend or database. A filter you want to share should live in the URL.

What state means

State is any value your app remembers while it runs. It can be a form input, a selected tab, a logged-in user, a cart, a task list, or an API result.

In a weekend project, unclear state causes messy code fast. You pass props everywhere, duplicate data, and lose work on refresh.

Your to-do

Choose the home

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Calling the API safely

3. Talk to your own API

4 min

Key point

One real connection

A full-stack repo needs your UI to talk to code you wrote on the server side.

For a weekend project, one useful API route is enough. It can list events, save feedback, check a coupon, or return a user profile.

What counts

Do not call only a public API from the browser and call it full-stack. That can be a good feature, but it does not prove you built a backend.

Your own API route should sit inside your repo. The frontend should fetch it. The page should show data that came from that route.

Your to-do

Pick one route

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Setting up and submitting

5. Set environment configuration

4 min

Key point

One rule

Environment config is for values that change by machine, deployment, or account. Code should not change when you move from your laptop to a teammate’s laptop or a hosting service.

Commit the example. Do not commit the real secret.

What belongs here

Put API keys, database URLs, auth secrets, and public base URLs in env files. For a weekend project, you may only have two or three values. That is fine.

Do not put normal UI text, button labels, or feature names in env files. Those belong in code.

Your to-do

Set the files

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Create a real .env.local file for your machine.
Create a .env.example file with the same variable names and safe dummy values.
Add .env.local and .env to .gitignore if your tool has not done it already.
Commit .env.example so teammates and reviewers know what to set.
Write setup instructions in README using the same variable names.

0 of 5 done

10 questions, 7 to pass.

Tip

Use AI safely

Ask an AI tool to compare two stack choices for your exact app and your team’s skills. Then check the answer for hidden complexity, paid services, and tools nobody can debug.

Do not accept a generated stack plan if it adds auth, Docker, Redis, queues, or cloud functions without a clear reason.

Prompt:
We are 3 college students building a weekend hackathon app: [one-line idea].
Our skills: [React basics, Node basics, SQL basics].
We need one UI, our own API route/backend, and simple data storage.
Suggest the smallest stack we can finish in 2 days.
Also list what not to add.

Example

Write the decision

Add a short stack note early. Put it in your README draft or a docs/stack.md file. This helps teammates stay aligned and helps reviewers understand your choices.

Project: Campus Lost and Found

Stack decision:
- Frontend: Next.js, because we can build pages and API routes in one repo.
- Styling: Tailwind CSS, because two teammates have used it before.
- Backend: Next.js API routes for posting and listing items.
- Storage: SQLite for the hackathon demo, because it is simple to run locally.

Not doing this weekend:
- Native mobile app
- OTP login
- Admin dashboard
- Payment or UPI flow
- Separate microservices

Example

State map example

Before coding, write a small state map in your README or notes. This makes your repo easier to review because teammates can see your decisions.

Example for a simple campus expense splitter:

State map

UI state:
- isAddExpenseModalOpen
- selectedMemberId
- formErrors

URL state:
- groupId
- month

Backend/database state:
- groups
- members
- expenses
- settlements

Browser storage:
- theme preference only

Never store:
- UPI PIN
- auth secrets
- private tokens

Tip

Use AI carefully

Ask ChatGPT, Gemini, or Claude to make a state map from your feature list. Then check every item yourself.

AI often suggests localStorage because it is easy. Change that if the data must survive refresh, work across devices, or be trusted by other users.

Prompt:
I am building a weekend full-stack app for a hackathon.
Features: add expenses, split by members, filter by month, show settlement summary.
Make a state map with four buckets: UI state, URL state, backend/database state, browser storage.
Also list anything that should never be stored in the browser.

Example

Next.js example

In Next.js App Router, place your route at app/api/projects/route.js. Your page can then call /api/projects from the browser.

This is enough to prove the UI is talking to your own backend route.

// app/api/projects/route.js
export async function GET() {
  const projects = [
    { id: 1, name: "Mess Menu", status: "Live" },
    { id: 2, name: "UPI Splitter", status: "Building" }
  ];

  return Response.json({ projects });
}

// app/page.js
"use client";

import { useEffect, useState } from "react";

export default function Home() {
  const [projects, setProjects] = useState([]);

  useEffect(() => {
    async function loadProjects() {
      const res = await fetch("/api/projects");
      const data = await res.json();
      setProjects(data.projects);
    }

    loadProjects();
  }, []);

  return (
    <main>
      <h1>Campus Builds</h1>
      <ul>
        {projects.map((project) => (
          <li key={project.id}>
            {project.name} - {project.status}
          </li>
        ))}
      </ul>
    </main>
  );
}

4. Show loading and failure

5 min

Key point

One thing to remember

Every API call has three visible states: loading, success, and failure. If you only design success, your app will feel broken during normal network delays.

A reviewer on mobile data should know what is happening, what went wrong, and what they can try next.

Why this matters

In a hackathon demo, your API may be slow because the free server is waking up, the college Wi-Fi is crowded, or the reviewer is on a hotspot.

A loading message stops people from clicking again and again. A failure message shows that you handled real-world use, not just the happy path.

Your to-do

Handle three states

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Create a loading state before you call your API.
Create an error state for failed requests or invalid responses.
Show the real data only after the request succeeds.
Give the user a retry button when retrying makes sense.
Keep messages short and specific.

0 of 5 done

Example

React fetch example

This example calls your own API route and renders all three states. Use the same pattern for dashboards, lists, profile pages, or search results.

import { useEffect, useState } from "react";

export default function ProjectList() {
  const [projects, setProjects] = useState([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState("");

  async function loadProjects() {
    setLoading(true);
    setError("");

    try {
      const res = await fetch("/api/projects");

      if (!res.ok) {
        throw new Error("Could not load projects");
      }

      const data = await res.json();

      if (!Array.isArray(data.projects)) {
        throw new Error("Projects data is not in the expected format");
      }

      setProjects(data.projects);
    } catch (err) {
      setError(err.message || "Something went wrong");
    } finally {
      setLoading(false);
    }
  }

  useEffect(() => {
    loadProjects();
  }, []);

  if (loading) {
    return <p>Loading projects...</p>;
  }

  if (error) {
    return (
      <div>
        <p>{error}</p>
        <button onClick={loadProjects}>Try again</button>
      </div>
    );
  }

  return (
    <ul>
      {projects.map((project) => (
        <li key={project.id}>{project.name}</li>
      ))}
    </ul>
  );
}

Tip

Use AI carefully

You can ask an AI tool: “Add loading, error, and retry states to this React component without changing the API path.”

Check the answer before pasting it. Make sure it does not remove your existing fields, does not invent a new endpoint, and still handles non-200 responses with res.ok.

Common mistake

Common weak spots

Do not show a blank page while waiting. A blank page looks like a crash.

Do not only use console.error. Reviewers cannot see your browser console during a quick demo. Put a useful message on the page.

Your to-do

Test failure on purpose

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Change the API path to a wrong one, like /api/projectz, and check that an error appears.
Stop your backend server and check that the page does not go blank.
Return bad JSON shape once and check that your validation catches it.
Restore the correct API path before committing.
Write a short note in the README if a page may take a few seconds on first load.

0 of 5 done

Your to-do

Do this now

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Pick one screen in your project that calls your own API.
Add loading, error, and success rendering to that screen.
Add a retry button for the error state.
Break the API path once to test the failure message.
Commit the change with a clear message, like add loading and error states.

0 of 5 done

Example

Example env files

This is enough for many full-stack hackathon apps. The frontend calls your own API. The backend may call a database or third-party service.

.env.local
API_SECRET_KEY=replace_with_real_secret
DATABASE_URL=postgresql://user:password@localhost:5432/weekend_app
NEXT_PUBLIC_APP_URL=http://localhost:3000

.env.example
API_SECRET_KEY=your_secret_key_here
DATABASE_URL=your_database_url_here
NEXT_PUBLIC_APP_URL=http://localhost:3000

.gitignore
.env
.env.local

Example

Read values safely

Fail early if a required backend value is missing. A clear error is better than a broken demo during judging.

// lib/env.js
export function requiredEnv(name) {
  const value = process.env[name];

  if (!value) {
    throw new Error(`Missing environment variable: ${name}`);
  }

  return value;
}

// Example usage in a server route only
const apiSecretKey = requiredEnv('API_SECRET_KEY');

Tip

Use AI carefully

Ask ChatGPT or Gemini to draft your .env.example and README setup steps from your project files. Then check every variable name against the code.

Also check that it did not suggest committing real keys. If it shows a secret-looking value, replace it with a placeholder before you paste.

Prompt:
Read these file names and code snippets. List the environment variables this app needs. Create a safe .env.example and README setup section. Do not include real secrets.

6. Keep the repo navigable

4 min

Key point

One main rule

A navigable repo answers one question fast: where should I look next? Your teammate, judge, or recruiter should find the UI, API, shared logic, and start command without asking you on WhatsApp.

What reviewers scan

Most reviewers do not read every file. They scan the root folder, package scripts, main app folder, API folder, and README headings.

Your job is not to create a perfect enterprise structure. Your job is to remove confusion from a weekend project.

Your to-do

Shape the folders

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Keep app code in one clear source folder, such as src or app.
Group files by feature when the project is small, such as auth, listings, or payments.
Keep API routes or backend code in a clearly named place, such as app/api, server, or backend.
Put reusable helpers in lib or utils only when more than one feature uses them.
Move old experiments to a notes folder or delete them before submitting.

0 of 5 done

Example

Simple repo map

This is enough for a small Next.js project with its own API route. Use the same idea for MERN, Express, Flask, or Django: separate UI, backend, helpers, and docs.

campus-lost-found/
  README.md
  package.json
  .env.example
  src/
    app/
      page.tsx
      items/
        page.tsx
      api/
        items/
          route.ts
    components/
      ItemCard.tsx
      EmptyState.tsx
    lib/
      storage.ts
      validators.ts
  public/
    screenshot.png

Common mistake

Common messy pattern

Do not leave files named final2.js, newBackend.js, test-copy.tsx, or temp.jsx in the main path. These make the project look unfinished, even when the app works.

Also avoid hiding key code inside random folders like misc or old. If a file matters, give it a real home and a real name.

Tip

Use AI carefully

You can ask an AI tool to suggest a folder structure for your existing files. Paste the file tree, not your secrets. Ask it to explain what to rename and what to delete.

Check the result yourself. AI often over-engineers small apps with too many layers. For a hackathon repo, fewer clear folders are better.

Prompt:
I am submitting a weekend full-stack hackathon project.
Here is my file tree. Suggest a simpler structure.
Keep it small. Do not add new libraries.
Tell me which files to rename, move, or delete.

[file tree here]

Example

Helpful package scripts

Scripts are navigation too. They tell someone how the project is meant to run, lint, or build. Keep script names boring and standard.

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  }
}

Your to-do

Do this now

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Open your repo root and list the top-level files and folders.
Rename unclear files so the name says what the file does.
Move UI, API, helpers, and components into obvious folders.
Delete unused experiments, generated junk, and duplicate copies.
Run the app once after moving files and fix broken imports.

0 of 5 done

7. Submit your full-stack repo

4 min

Key point

Reviewer-ready beats done

Your submission is not just code. It is a public repo that a teammate, judge, or recruiter can open and understand in five minutes.

Before you submit, check the repo from a stranger’s view. They should see what the app does, how to run it, where the API is, and what environment variables are needed.

Your to-do

Final repo check

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Open your repo in a private or incognito browser to see what a public reviewer sees.
Confirm the app starts from the README commands on a fresh clone.
Find your own API route or backend folder and make sure it is named clearly.
Check that .env files are not committed, and .env.example is present.
Click through the main user flow once and fix broken states before submitting.

0 of 5 done

Example

README finish block

Add a short submission block near the top of your README. Keep it practical. A reviewer should not search through paragraphs to find the basics.

Project: Mess Splitter

What it does:
A simple app for hostel friends to add shared expenses and see who owes whom.

Live demo:
Add your deployed app link here, if available.

Main stack:
Next.js, API routes, SQLite with Prisma

Run locally:
1. Clone the repo
2. Copy .env.example to .env
3. Run npm install
4. Run npm run dev
5. Open http://localhost:3000

Environment variables:
DATABASE_URL="file:./dev.db"

API proof:
POST /api/expenses adds an expense
GET /api/expenses returns saved expenses

Test account or sample data:
Use any name and amount on the Add Expense page.

Common mistake

Do not hide setup

A common mistake is writing only “npm install and npm run dev”. That is not enough for a full-stack repo.

If your app needs a database URL, API key, seed command, or login steps, write them clearly. If reviewers cannot run it, they will assume it is unfinished.

Tip

Use AI as reviewer

Paste your README into ChatGPT, Gemini, or Claude and ask: “Can a first-time reviewer run this project from these instructions? List missing steps only.”

Check the answer yourself. AI may invent commands or misunderstand your stack. Only add steps you have tested locally.

Your to-do

Submission checklist

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Set the repository visibility to public before adding the final link.
Remove unused files, old screenshots, and secret keys from the repo.
Add screenshots or a short demo GIF if your hackathon form allows it.
Mention the API route or backend feature in the README, not only the UI.
Copy the exact public GitHub repo URL into the HackIndia submission form.

0 of 5 done

Your to-do

Do this now

Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.

Clone your repo into a new folder and run it using only the README.
Update the README with app purpose, stack, setup, env variables, and API proof.
Open the repo as a public visitor and check that important files are visible.
Submit the public repo link in your hackathon project form.

0 of 4 done

Full-Stack

1. Pick a weekend-sized stack

One rule

Weekend-sized means small

Use this filter

Good stack choices

2. Decide where state lives

One rule

What state means

Choose the home

3. Talk to your own API

One real connection

What counts

Pick one route

5. Set environment configuration

One rule

What belongs here

Set the files

Common stack trap

Use AI safely

Write the decision

Do this now

Common mistake

State map example

Use AI carefully

Good enough boundary

Do this now

Next.js example

Use AI carefully

Common mismatch

Do this now

4. Show loading and failure

One thing to remember

Why this matters

Handle three states

React fetch example

Use AI carefully

Common weak spots

Test failure on purpose

Do this now

Example env files

Public means public

Read values safely

Use AI carefully

Do this now

6. Keep the repo navigable

One main rule

What reviewers scan

Shape the folders

Simple repo map

Common messy pattern

Use AI carefully

Helpful package scripts

Do this now

7. Submit your full-stack repo

Reviewer-ready beats done

Final repo check

README finish block

Do not hide setup

Use AI as reviewer

Submission checklist

Do this now