stamp/README.md

Stamp

Stamp is a quiz application geared towards individuals who want to quickly cycle through questions and receive immediate feedback.

Question Format

Questions must be provided in CSV format. There is no limit to the number of CSV files that can be loaded.

CSV Structure

Each CSV file must contain the following columns:

Column	Description	Format
Question	The question text	String (Include notes if multiple answers are expected)
Answer	Available answers	JSON array of objects with answer text and is_correct flag

Question Types

The system automatically determines the question type based on the answer structure:

• Multiple Choice: When multiple answers have is_correct: true
• Text Input: When only a single answer option is provided

Example

Question,Answer
"What is the capital of France?","[{\"text\": \"Paris\", \"is_correct\": true}, {\"text\": \"Lyon\", \"is_correct\": false}]"
"Name two primary colors (select all that apply)","[{\"text\": \"Red\", \"is_correct\": true}, {\"text\": \"Blue\", \"is_correct\": true}, {\"text\": \"Green\", \"is_correct\": false}]"

example.csv in the root of the repository can be loaded in the app as an example.

Running with Docker (Recommended)

Prerequisites

• Docker
• Docker Compose

Quick Start

To run the entire application using Docker, simply run:

# Clone the repository (if you haven't already)
git clone <your-repo-url>
cd stamp

# Build and start both services
docker-compose up --build

This will:

1. Build and start the FastAPI backend on port 8000
2. Build and start the React frontend on port 4000

Docker Networking

In the Docker environment:

• The frontend container communicates with the backend using the hostname backend (the service name in docker-compose.yml)
• From your host machine, both services are accessible via localhost on their respective ports
• Other devices on your network can access both services using your machine's IP address

Access the Application

• Frontend: http://localhost:4000
• Backend API: http://localhost:8000/docs (Swagger UI)

Accessing from Other Devices on Your Network

To access the application from other devices on your local network:

1. Find your host machine's IP address:

   # On Linux/macOS
   ifconfig | grep "inet "
   # On Windows
   ipconfig
   

2. Access using that IP:
   • Frontend: http://:4000
   • Backend: http://:8000

Docker Commands

# Start in detached mode
docker-compose up -d

# Stop services
docker-compose down

# View logs
docker-compose logs -f

# Rebuild after changes
docker-compose up --build

Manual Setup (Without Docker)

If you prefer to run without Docker:

Backend Setup

# Navigate to backend directory
cd backend/

# Install uv
pip install uv

# Create and activate virtual environment
uv venv
source .venv/bin/activate

# Install dependencies
uv sync

# Run the server
uvicorn src.main:app --host 0.0.0.0 --port 8000

Frontend Setup

# Navigate to frontend directory
cd frontend/

# Install dependencies
npm install

# Start the development server
npm start

Access the frontend at http://localhost:4000

Troubleshooting Connection Issues

If the frontend can't connect to the backend:

1. Check container logs:

docker-compose logs backend
docker-compose logs frontend

2. Test the backend API directly:

curl -v http://localhost:8000/docs

3. Make sure the backend is running before accessing the frontend:

docker ps

4. Try rebuilding the containers:

docker-compose down
docker-compose build --no-cache
docker-compose up

5. Check network communication:

# Enter the frontend container
docker exec -it stamp-frontend /bin/sh

# Test connection to backend (use service name, not localhost)
curl -v http://backend:8000/
exit

6. Use the network testing script:

./scripts/test-network.sh

This script will automatically detect your LAN IP and test both local and network connectivity.