Daycast - Project Guide

🎯 What is Daycast?

Daycast is a platform for operating smart vending machines. It allows users to:

Scan a QR code on the machine
Open the machine door
Take whatever products they want
Close the door and pay automatically

🏗️ Architecture: The Two Systems

🚀

Daycast (Active)

TheNewStand-Co/newstand-platform

📱 Frontend PWA (React + XState)
⚡ Backend API (Django 5.2 + DRF)
💳 Payment Processing (Stripe)
🎨 Modern UI/UX
📊 Analytics & Metrics

🏚️

TNS-Web (Legacy)

TheNewStand-Co/tns-web

🔧 Hardware Control (SandStar)
🚪 Door Open/Close Commands
📦 Product Detection
🔌 Legacy Integrations
🐍 Django 3.0.11

🔌 Hardware Proxy Mode (Bridge Strategy)

The Hardware Proxy is the strategy for deploying new machines. This approach allows SandStar (the hardware provider) to continue their standard installation process without any changes - they configure machines to point to TNS-Web as they always have.

How it works: Daycast handles the user interface and Stripe payments, while TNS-Web acts as a bridge to control the physical hardware (door open/close, product detection).

📅 Migration Plan: This bridge will be tested and validated over time. Once stable, the legacy TNS-Web system will be gradually deprecated, and new machines will be migrated to connect directly to the Daycast system without the proxy layer.

Machines with hardware_proxy = True use this mode. Check the admin panel to see which machines are in proxy mode.

💡

Recommended Setup: Clone both repos into a parent folder (e.g., daycast-workspace/) to use Claude Code at the root level for both projects simultaneously.

daycast-workspace/
├── newstand-platform/    # Daycast (active)
└── tns-web/              # Legacy system
                        

🔄 Transaction Flow

Step 1

👤 User

Scans QR

→

Step 2

📱 PWA

React App

→

Step 3

⚡ Daycast

Creates TX

→

Step 4

🔧 TNS-Web

Opens Door

→

Step 5

🏭 Hardware

SandStar

📋 Transaction States

Status	Code	Description
PENDING	1	Transaction started, door open
SUCCESSFUL	2	Payment completed successfully
PENDING_PAYMENT	9	Door closed, awaiting payment
FAILED	3	Error in the process

📁 Code Structure

🚀 Daycast (newstand-platform)

backend/
├── apps/              # Django apps
│   ├── users/          # Auth, roles, profiles
│   ├── organizations/  # Org hierarchy
│   ├── products/       # Catalog, menus
│   ├── machines/       # Vending machines
│   ├── transactions/   # Purchases, payments
│   └── common/         # Shared utils, tasks
├── api/              # DRF ViewSets, serializers
├── config/           # Settings, URLs, ASGI
└── tests/            # pytest tests

frontend/
├── src/
│   ├── components/   # atoms/, molecules/, organisms/, pages/
│   ├── machines/     # XState state machines
│   ├── services/     # API calls
│   ├── hooks/        # Custom React hooks
│   └── utils/        # Helpers
└── envs/             # Environment files
                        

🔶 TNS-Web (Legacy)

tns-web/
├── accounts/         # User auth, addresses
├── cards/            # Loyalty cards
├── payments/         # Stripe, balance
├── vending/          # Machine operations
├── integrations/     # Third-party APIs
├── business/         # Enterprise, teams
├── tns/              # Settings, URLs, celery
└── pytests/          # Tests
                        

TNS-Web has 23+ Django apps. Key ones for vending: vending/, payments/, integrations/

🔑 Key Files to Know

File	Purpose
`backend/apps/transactions/`	Transaction model, states, payment logic
`backend/apps/machines/models.py`	VendingMachine model, test modes, hardware proxy
`frontend/src/machines/VendingMachine.ts`	Main XState machine for purchase flow
`frontend/src/services/index.ts`	All API calls (vmStart, vmPay, etc.)
`tns-web/vending/views.py`	Legacy vending endpoints (hardware control)
`tns-web/integrations/sandstar/`	SandStar hardware API integration

⚙️ Project Setup

📋 Requirements

Docker Desktop

To run services

Node.js 18+ & Yarn

For frontend

1Password CLI

For secrets

🚀 Installation Steps

1
Clone the repositories
mkdir daycast-workspace && cd daycast-workspace git clone https://github.com/TheNewStand-Co/newstand-platform.git git clone https://github.com/TheNewStand-Co/tns-web.git
2
Setup Claude Code Skills
cd newstand-platform/skills ./setup.sh
3
Get environment files
Search in 1Password under "Daycast":
• Backend: "Daycast | Backend env.local"
• Frontend: "Daycast | Frontend env"
4
Setup Backend
cd newstand-platform/backend make setup # Docker, migrations, superuser
5
Setup Frontend
cd ../frontend yarn install

🔶 TNS-Web Setup (Legacy - for Hardware Bridge)

TNS-Web is needed when working with vending machines that use the Hardware Proxy bridge.

1
Get environment file
Search in 1Password: "TNS-Web | env"

cd tns-web cp env.example .env # Paste values from 1Password
2
Copy Docker Compose file
cp .docker/docker-compose/docker_compose_dev.yml docker-compose.yml
3
Build and start containers
docker-compose build docker-compose up -d
4
Run migrations (first time only)
docker-compose exec tns-web python manage.py collectstatic --noinput docker-compose exec tns-web python manage.py migrate

TNS-Web runs on http://localhost:8000 - Note: If running both, change Daycast backend port.

🔗 URLs

Environment	URL
Local Frontend	http://localhost:3000
Local API	http://localhost:8000/api/v1/
Local Admin	http://localhost:8000/admin/
Staging Admin	https://backend.staging.daycast.co/admin/
Production Admin	https://backend.daycast.co/admin/

🔐 Credentials: Search in 1Password under "Daycast" for admin credentials.

🌐 External Services

☁️ Azure (Hosting & Logs)

Account: azure@newstand.com (credentials in 1Password)

Web Apps:

Production	`web-app` Portal
Staging	`daycast-staging` Portal
TNS-Web	`tns-web` (prod & staging) Rancher

View Logs with Azure CLI:

# Login to Azure
az login

# Stream live logs (Production)
az webapp log tail --name web-app --resource-group app

# Stream live logs (Staging)
az webapp log tail --name daycast-staging --resource-group app

# Download logs
az webapp log download --name web-app --resource-group app

# TNS-Web logs: Use Rancher dashboard instead
                        

Azure Portal - Use azure@newstand.com

🐛 Sentry (Error Tracking)

Monitor errors and exceptions in production.

Organization	new-stand-ka.sentry.io
Project: Daycast	ns-platform
Project: TNS-Web	tns-web

🔐 Credentials in 1Password under "Sentry"

📧 Mailgun (Email Service)

Transactional emails: receipts, password resets, notifications.

Dashboard	app.mailgun.com
Domain	`mg.daycast.co`

🔐 Credentials in 1Password under "Mailgun"

🛡️ Cloudflare (DNS & CDN)

DNS management, CDN, and Cloudflare Pages for frontend hosting.

Dashboard	dash.cloudflare.com
Domain	`daycast.co`
Pages (Frontend)	`daycast-pwa`

🔐 Credentials in 1Password under "Cloudflare"

📝 Notion (Documentation)

Project documentation, specs, and historical context. Contains mixed TNS-Web and Daycast docs.

Project Docs

New Stand Workspace

🔐 Request access from team lead

💡

All credentials are in 1Password. Search for: "Azure", "Sentry", "Mailgun", or "Cloudflare"

🤖 Working with Claude Code

This project is developed using Claude Code as the primary AI assistant. Claude has access to specialized skills and agents that understand the Daycast codebase.

💡

First time setup: Run cd skills && ./setup.sh to configure Claude Code skills for this project.

📚 Available Skills

Skills are auto-invoked based on context. You can also call them explicitly.

django-drf-patterns

Django 5.2 + DRF: ViewSets, serializers, models, async tasks

react-xstate-patterns

React 18 + XState: Components, hooks, state machines

stripe-integration

Payments: Checkout, webhooks, SetupIntents

db-query

PostgreSQL queries with Azure credentials

sandstar-api

SandStar VMS hardware integration

daycast-azure

Azure resources: Key Vault, Web Apps, DB

review

Automated code review with prioritization

docker-cicd-patterns

Docker, Compose, GitHub Actions

project-guide

Opens this documentation in browser

🤖 Available Agents

Agent	Purpose	When Used
backend-reviewer	Python/Django code review	When reviewing .py files
frontend-reviewer	React/TypeScript code review	When reviewing .tsx/.ts files
security-auditor	Security vulnerability audit	Security-sensitive code, pre-deploy
test-writer	Generates pytest/Vitest tests	When writing tests
architect	Architecture decisions	Feature design discussions

☁️ Azure MCP Integration

Claude Code has access to Azure MCP (Model Context Protocol) which allows direct interaction with Azure resources without leaving the editor.

What you can do:

Database Queries	Use `/db-query` skill - Claude retrieves credentials from Azure Key Vault automatically
View Logs	Ask Claude to "show logs from web-app" or "tail staging logs"
Key Vault	Claude can read secrets from `daycast-keyvault` for scripts
Resource Info	Ask about web app status, settings, or configuration

💡

Prefer Azure MCP over CLI when working in Claude Code. It's faster and doesn't require manual login. For terminal work outside Claude, use az login with azure@newstand.com.

Example prompts:

# Database
"Query the database for failed transactions today"
"Show me users who signed up this week"

# Logs
"Show recent logs from production web-app"
"Check for errors in staging"

# Azure Resources
"What's the status of daycast-staging web app?"
"Get the database password from Key Vault"
                    

⌨️ Useful Commands

Claude Skills

/review-pr 123    # Review a PR
/db-query          # Query database
/test              # Generate tests
/review            # Code review
                        

Ask Claude

# Example prompts:
"Explain how transactions work"
"Review this PR for security issues"
"Write tests for this ViewSet"
"Query the database for pending transactions"
                        

📋 Development Guidelines

These are the coding standards and best practices for the Daycast project. All contributors should follow these guidelines.

🐍 Backend (Django)

Code Style

Formatter	Black (line-length: 88)
Imports	isort with Django profile
Linting	flake8
Type Hints	Required on all public functions

✅ DO

Use snake_case for functions, variables, modules
Use PascalCase for classes
Add type hints to public functions
Use select_related / prefetch_related for related objects
Use Django's ORM for database queries
Write tests for ViewSets and services
Use @extend_schema for API documentation

❌ DON'T

Write raw SQL (use ORM instead)
Log sensitive data (tokens, passwords)
Skip migrations in commits
Use print() instead of logging
Put business logic in views (use services)
Commit .env files

⚛️ Frontend (React)

Code Style

Linting	ESLint (airbnb-style)
Formatting	Prettier (integrated)
TypeScript	Strict mode enabled

✅ DO

Use PascalCase for components
Use camelCase for hooks and utils
Use XState for complex state flows
Follow Atomic Design (atoms, molecules, organisms)
Use Styled Components for styling
Write Vitest tests for components

❌ DON'T

Use any type (use proper types)
Use inline styles (use Styled Components)
Leave console.log in production code
Use Redux (we use XState)
Skip TypeScript errors with // @ts-ignore

📝 Git & PRs

Commit Messages

Use conventional commits:

feat: Add new vending machine flow
fix: Resolve transaction timeout issue
chore: Update dependencies
docs: Add API documentation
refactor: Simplify payment logic
test: Add tests for transaction service
                    

Pull Request Checklist

Link related issues
Describe scope and changes
Flag any migrations or env var changes
Include screenshots for UI changes
Ensure CI is green
Request appropriate reviewers

🧪 Testing

🐍 Backend (Daycast)

# Run all tests
make test

# Run with coverage (80% threshold)
make test-coverage

# Run specific app tests
make test-app APP=transactions

# Run fast (parallel, no coverage)
make test-fast
                        

Tests location: backend/tests/<app>/test_*.py

⚛️ Frontend (Daycast)

# Run all tests
yarn test

# Watch mode
yarn test:watch

# Coverage report
yarn test:coverage
                        

Tests colocated: Component.test.tsx next to component

🔶 TNS-Web (Legacy)

# Run tests inside container
docker-compose exec tns-web python manage.py test -v 2

# Run pytest
docker-compose exec tns-web pytest --no-cov
                    

Tests location: pytests/

📖 API Documentation

Daycast Swagger	localhost:8000/api/docs/
Daycast ReDoc	localhost:8000/api/redoc/
TNS-Web Swagger	localhost:8000/data/swagger/

❓ Frequently Asked Questions

Vending & Transactions

What happens when a user scans a QR code? ▼

User scans QR → Opens PWA with machine ID
PWA calls /api/v1/transactions/setup/ to create SetupIntent
User enters card details (Stripe Elements)
PWA calls /api/v1/transactions/start/
Backend creates Transaction + calls TNS-Web to open door
Door opens, user takes products
Door closes → TNS-Web sends webhook with products taken
Backend processes payment via Stripe
Receipt sent to user

What is "Hardware Proxy" mode? ▼

Hardware Proxy is the bridge between Daycast and the legacy TNS-Web system for controlling vending machine hardware.

Daycast handles: UI, user auth, Stripe payments
TNS-Web handles: Door control, product detection (via SandStar)

Machines with hardware_proxy = True use this mode.

What are the different transaction statuses? ▼

PENDING (1)	Door is open, user selecting products
SUCCESSFUL (2)	Payment completed
FAILED (3)	Error occurred
PENDING_PAYMENT (9)	Door closed, processing payment
DOOR_MALFUNCTION (6)	Door error detected
EMPTY_VEND (7)	No products taken

What is "Free Vend" mode? ▼

Machines with is_free_vend = True allow users to take products without payment. The door opens normally but no charge is made.

Use case: Employee perks, promotional events, or subsidized vending.

Development

Where do I find credentials for staging/production? ▼

All credentials are stored in 1Password under the "Daycast" vault:

Daycast | Backend env.local - Local env file
Daycast | Frontend env - Frontend env file
Daycast | Admin credentials - Staging/prod admin

How do I test the vending flow locally? ▼

Start backend: make up
Start frontend: yarn dev
Go to admin → Machines → Enable test_mode
Use test mode "full" to simulate products taken
Scan QR or navigate to /qr/?vending_machine=MACHINE_ID

Use Stripe test cards: 4242 4242 4242 4242

🔧 Troubleshooting Guide

Common issues and how to resolve them. This guide is also useful for the support team.

🚫 Development Issues

Docker won't start

▼

Verify Docker Desktop is running
Check ports: lsof -i :8000 and lsof -i :5432
Restart: make down && make up
Rebuild: docker-compose build --no-cache

Frontend won't connect to backend

▼

Check backend is running: curl http://localhost:8000/api/v1/
Verify VITE_API_URL in frontend env
Check CORS settings in backend
Clear browser cache and retry

⏳ Transaction Issues

Transaction stuck in PENDING

▼

The door closed but payment wasn't processed.

Check if TNS-Web webhook was received (check order_detail in transaction)
Review TNS-Web logs for communication errors
Verify Hardware Proxy configuration on the machine
Use /db-query skill to investigate the state

# Check transaction in database
SELECT id, status, order_detail, door_closed_at
FROM transactions_transaction
WHERE id = 'TRANSACTION_ID';
                            

Stripe SetupIntent Error

▼

SetupIntent already succeeded: User navigated back. A new SetupIntent is generated automatically.
SetupIntent expired: More than 24 hours passed. Start a new transaction.
Invalid payment method: Card declined or incorrect data.

Hardware Proxy not working

▼

Verify the machine has hardware_proxy = True
Check Dynamic Preferences in Admin → Global Preferences → Vending:
- TNS_VENDING_API_URL
- TNS_VENDING_API_TOKEN
Test connection from Django shell:
from apps.integrations.tns_vending_client import tns_vending_client success, response = tns_vending_client.list_vending_machines() print(success, response)

Door won't open

▼

Check machine status in admin (should be "active")
Verify external_id matches SandStar machine ID
Check TNS-Web logs for hardware errors
Verify SandStar API credentials in TNS-Web admin
Test direct SandStar API call (ask infra team)

💳 Payment Issues

Payment failed after door closed

▼

Check Stripe dashboard for the payment attempt
Look at TransactionSetupIntent for error messages
Common causes:
- Card declined
- Insufficient funds
- Card expired
- 3D Secure failed
Transaction will be in FAILED status

User charged but products not dispensed

▼

This requires manual refund investigation.

Find transaction in admin
Check order_detail for items taken
Compare with Stripe charge amount
If mismatch, issue refund via Stripe dashboard
Update transaction status to FULLY_REFUNDED or PARTIALLY_REFUNDED