Web Application via Claude Code

0-instructions.md

Instructions

I discovered that Claude Code, unlike current Agents in IDEs (Cascase in Windsurf, Cursor Agents), can follow instructions outlined in another file or in a large prompt. This allows scaffolding new architectures quickly and implementing specific applications on top.

Tips

• Since Claude Code will use the directory as context, I find it useful to hide context. This allows us to greenfield progressively. I find too much context results in undesirable results.

Follow this process:

1. Copy contents of current step (1-4) to spec.md in root of project
2. Prompt claude follow the instructions in spec.md
3. Verify output
4. Remove spec.md from project
5. Prompt Claude Code /init
6. Repeat until steps completed

One-liners

python -c "import urllib.request; print(urllib.request.urlopen('https://gist.githubusercontent.com/buwilliams/db39f23acb1e6ad9595c99727448d530/raw/ae27d14504a83c0c6bbe831fce9a8907bda4f4c8/1-backend.md').read().decode('utf-8'))" | claude -p --allowedTools "Bash,Edit,Write"

python -c "import urllib.request; print(urllib.request.urlopen('https://gist.githubusercontent.com/buwilliams/db39f23acb1e6ad9595c99727448d530/raw/60e36dd48e38b6b8e5d1fc1d26e3fd8fe78b7b35/2-frontend.md').read().decode('utf-8'))" | claude -p --allowedTools "Bash,Edit,Write"

python -c "import urllib.request; print(urllib.request.urlopen('https://gist.githubusercontent.com/buwilliams/db39f23acb1e6ad9595c99727448d530/raw/60e36dd48e38b6b8e5d1fc1d26e3fd8fe78b7b35/3-design.md').read().decode('utf-8'))" | claude -p --allowedTools "Bash,Edit,Write"

python -c "import urllib.request; print(urllib.request.urlopen('https://gist.githubusercontent.com/buwilliams/db39f23acb1e6ad9595c99727448d530/raw/0e7387d0c896fd30e04f3ba8c91669226d51216e/4-application.md').read().decode('utf-8'))" | claude -p --allowedTools "Bash,Edit,Write"

1-backend.md

Backend

Modular python backend with FastAPI and unit tests.

Run.py script

• script is in the root directory
• scripts always configures and uses Python virtual environment
• ensure graceful shutdown of application when Ctrl+C is pressed
• run.py will show help text
• run.py help will show help text
• run.py web will start the backend
• run.py db:migrate will run database migrations
• run.py db:clean will clean the database
• run.py db:seed will seed the database
• run.py test will run tests
• run.py coverage will show test coverage

Run.sh script

• simple pass through script to execute run.py script
• ensure graceful shutdown of application when Ctrl+C is pressed

Database

• database is in backend directory
• use SQLModel library
• uses SQLite as database
• SQLModel is stored as db/database.db
• migrations are in db/migrations
• seeds are in db/seeds

Python Code Organization

• requirements.txt is in root directory
• python is in backend directory
• modular code organization
• app.py is the main application file and is in backend
• routes are in backend/routes
• models are in backend/models
• services are in backend/services
• tests are in backend/tests

REST API

• all endpoints begin with /api/
• create a simple hello world endpoint in backend/routes/hello.py

Static Web Server

• static files are in frontend/ directory
• any endpoint that doesn't begin with /api/ will be served from frontend/ directory
• create simple hello world index.html files in frontend/index.html

Best Practices

• unit tests with pytest
• high level of test coverage

Unit tests

• write tests for run.py
• write tests for backend/app.py
• write tests for backend/routes/hello.py

requirements.txt for python dependencies

• Python 3.10
• FastAPI 0.115.12
• uvicorn 0.34.1
• SQLModel 0.0.24
• pytest 8.3.5
• pytest-asyncio 0.26.0
• pytest-cov 6.1.1
• httpx 0.28.1

2-frontend.md

Frontend

Architecture

• Frontend should be fully static with no build process
• Use <script> tags to import UI components
• Use Alpine.js for client-side interactivity
• Make REST API calls to /api/
• Components stored in frontend/components/

UI Components

Organization

• Store common components in frontend/components/
• Store feature components in frontend/features/
• Store global css in frontend/css/
• Store global js in frontend/js/

Loading Components

• Create a custom load() function to load components, and use Alpine.js directives to load them.
• Function stored in frontend/js/load.js

document.addEventListener('alpine:init', () => {
  // Custom x-load directive
  Alpine.directive('load', (el, { expression }, { evaluate, effect, cleanup }) => {
    const load = async (templateUrl) => {
        try {
            const response = await fetch(templateUrl);
            if (!response.ok) {
                throw new Error(`Failed to load template: ${response.status}`);
            }
            return await response.text();
        } catch (error) {
            console.error('Error loading template:', error);
            return '';
        }
    };

    let templateHtml = '';

    // Create a container for the template content
    const container = document.createElement('div');
    el.appendChild(container);

    // Load and render the template
    const updateTemplate = async () => {
        const url = evaluate(expression);
        templateHtml = await load(url);
        if (templateHtml) {
            container.setAttribute('x-html', templateHtml);
            Alpine.bind(container, {
                'x-data': { templateHtml }
            });
        }
    };

    // Initial load
    updateTemplate();

    // Cleanup when the element is removed
    cleanup(() => {
        container.remove();
    });
  });
});

Alpine.js Syntax

All components use Alpine.js syntax from https://alpinejs.dev/

Directives

• x-data
• x-init
• x-show
• x-bind
• x-on
• x-text
• x-html
• x-model
• x-modelable
• x-for
• x-transition
• x-effect
• x-ignore
• x-ref
• x-cloak
• x-teleport
• x-if
• x-id

Magics

• $el
• $refs
• $store
• $watch
• $dispatch
• $nextTick
• $root
• $data
• $id

Globals

• Alpine.data()
• Alpine.store()
• Alpine.bind()

3-design.md

Design System Guidelines

Core Design Principles

All global styles are stored in frontend/css/app.css

Typography System: 4 Sizes, 2 Weights

• 4 Font Sizes Only:
  • Size 1: Large headings
  • Size 2: Subheadings/Important content
  • Size 3: Body text
  • Size 4: Small text/labels
• 2 Font Weights Only:
  • Semibold: For headings and emphasis
  • Regular: For body text and general content
• Consistent Hierarchy: Maintain clear visual hierarchy with limited options

8pt Grid System

• All spacing values must be divisible by 8 or 4
• Examples:
  • Instead of 25px padding → Use 24px (divisible by 8)
  • Instead of 11px margin → Use 12px (divisible by 4)
• Consistent Rhythm: Creates visual harmony throughout the interface

60/30/10 Color Rule

• 60%: Neutral color (white/light gray)
• 30%: Complementary color (dark gray/black)
• 10%: Main brand/accent color (e.g., red, blue)
• Color Balance: Prevents visual stress while maintaining hierarchy

Clean Visual Structure

• Logical Grouping: Related elements should be visually connected
• Deliberate Spacing: Spacing between elements should follow the grid system
• Alignment: Elements should be properly aligned within their containers
• Simplicity Over Flashiness: Focus on clarity and function first

Spacing Guidelines

• All spacing values MUST be divisible by 8 or 4:

  • ✅ DO: Use 8, 16, 24, 32, 40, 48, etc.
  • ❌ DON'T: Use 25, 11, 7, 13, etc.

• Practical examples:

  • Instead of 25px padding → Use 24px (divisible by 8)
  • Instead of 11px margin → Use 12px (divisible by 4)
  • Instead of 15px gap → Use 16px (divisible by 8)

• Use Tailwind's spacing utilities:

  • p-4 (16px), p-6 (24px), p-8 (32px)
  • m-2 (8px), m-4 (16px), m-6 (24px)
  • gap-2 (8px), gap-4 (16px), gap-8 (32px)

• Why this matters:

  • Creates visual harmony
  • Simplifies decision-making
  • Establishes predictable patterns

60/30/10 Color Rule

Color Distribution

• 60%: neutral color (bg-background)

  • Usually white or light gray in light mode
  • Dark gray or black in dark mode
  • Used for primary backgrounds, cards, containers

• 30%: complementary color (text-foreground)

  • Usually dark gray or black in light mode
  • Light gray or white in dark mode
  • Used for text, icons, subtle UI elements

• 10%: accent color (brand color)

  • Your primary brand color (red, blue, etc.)
  • Used sparingly for call-to-action buttons, highlights, important indicators
  • Avoid overusing to prevent visual stress

Common Mistakes

• ❌ Overusing accent colors creates visual stress
• ❌ Not enough contrast between background and text
• ❌ Too many competing accent colors (stick to one primary accent)

Visual Hierarchy

Design Principles

• Simplicity over flashiness: Focus on clarity and usability
• Emphasis on what matters: Highlight important elements
• Reduced cognitive load: Use consistent terminology and patterns
• Visual connection: Connect related UI elements through consistent patterns

Implementation

• Maintain consistent spacing between related elements
• Align elements properly within containers
• Logical grouping of related functionality

Experience Design

Motion & Animation

• Consider transitions between screens and states
• Animation purpose: Enhance usability, not distract
• Consistent motion patterns: Similar elements should move similarly

Implementation

• Test experiences across the entire flow
• Design with animation in mind from the beginning
• Balance speed and smoothness for optimal user experience

4-application.md

Project Estimation Web Application

Overview

This specification defines a web-based project estimation tool designed to streamline project planning and cost estimation for development teams and clients. The application prioritizes an elegant, intuitive user experience (UX), a visually appealing user interface (UI), and minimal dependencies. It supports user authentication, project and story management, developer-driven estimation workflows, and client-facing interactive estimate viewing, all with real-time updates.

Requirements

User Management

1. Login & Registration

   • Developer: Full access to create/edit projects, stories, and estimates.
     • Users register with an email and password.
     • Users log in with credentials.
   • Client: Does not require authentication. View-only access to estimates via a shared link.

2. Role-Based Access Control

   • Developers perform all actions (create, edit, view).
   • Clients view and toggle estimates interactively.
   • One developer "owns" a project and grants access to other developers
   • Owner can transfer ownership to another developer

Project Management

1. Add, Edit, and View Projects

   • Create projects with name, description, and optional metadata (e.g., client name).
   • Edit project details.
   • View projects individually or in a list.

2. Phases

   • Projects support multiple phases (default: one phase).
   • Phases contain stories and can be added/edited.

3. Stories

   • Stories are tasks within a phase, with title, description, and estimates.
   • Add, edit, and view stories per project/phase.
   • Each developer provides an independent estimate.
   • Owner select estimate to use our of all provided developer estimates.

Estimation Features

1. Fine-Grained Cost Estimates

   • Story-level estimates with 50% and 90% confidence levels.
   • Aggregated into a project-level cost estimate.

2. Project Estimate Generation

   • Automatically calculated in real-time (no manual "generate" button).
   • Includes story estimates, additional factors, and blended hourly rate.

3. Developer Estimation Interface

   • Assign developers to project as optional or required to provide estimates.
   • Show the number of developers who provided estimates.
   • Show list of developers who have provided estimates.
   • Developers input hidden estimates in story points (1 point = 1 ideal staff day).
   • Shareable estimate link for clients.

Bulk Story Import

1. Import Stories to Phase in a Project
   • Upload a CSV file.
   • Textarea to paste CSV contents into.

Client Dashboard

1. View All Estimates

   • Private link to their dashboard.
   • List of all estimates by order of completion.

2. View Estimate Details

   • Select an Estimate.
   • Toggle on/off stories to see price adjustments.
   • Toggle on/off phases to see price adjustments.

Estimate Calculation Methodology

Story-Level Estimates

• All estimates, percentages, and sums should be whole numbers
• Two estimates (50%, 90%) in Fibonacci points (0.25, 0.5, 1, 2, 3, 5, 8, 13, 21, 34, 55).
• Hidden until submitted, then reconciled.

Project-Level Estimate

1. Uncertainty
   • σ = sqrt((90% - 50%)²) / 2.
2. Most Likely
   • Sum(50%) + 2 * sqrt(Sum((90% - 50%)²)).
3. Total Cost
   • Most Likely * Hourly Rate * (1 + Sum(Additional Factors)).
4. Calibration
   • Adjustable factor based on team velocity.

Reference

• Agile Estimating and Planning, Chapter 17, Mike Cohn.