App Development Kit

Weeks 8-10: Product Sprint

What This Kit Is For

This kit gives your team a working starting point for a small AI-powered web app. You will not begin from a blank screen. Instead, you will define the app idea, customize the starter files with Cowork/Codex, test the app on your computer, and then deploy it to Railway so other people can open it through a public URL.

The goal is not to become a software engineer in one week. The goal is to understand the basic workflow behind many AI applications: a user enters a request, the app sends that request to a model through an API, the model returns an answer, and the app displays the result.

It is acceptable to use synthetic data to demonstrate the app, and it is also acceptable for the app to implement one useful part of a larger product concept.

Phase 1: Initial Setup

This guide uses the command-line app built into your computer: Terminal on macOS and PowerShell on Windows. In the command-line blocks below, $ and PS> show where the command line starts. Type only the command that comes after those symbols.

1. Create the Project Folder

1. Download and unzip App_Development_Kit.zip.
2. Place the unzipped folder on your Desktop.
3. Rename the folder myapp.
4. Download and sign into either Cowork or Codex. Each team should plan to use one paid coding assistant account, roughly $20 per month, for the duration of the product sprint.
5. Open the folder in Cowork/Codex.
6. Ask Cowork/Codex to read AppPlan.md and App_Development_Kit.html before editing anything.

Files ending in .md and .env, such as AppPlan.md and local.env, are plain text files. You can edit them in TextEdit on macOS or Notepad on Windows. If you use TextEdit, choose Format > Make Plain Text before saving.

2. Install Node.js and npm

Node.js lets the starter app run on your computer. npm comes with Node.js and installs the app’s dependencies. In plain English, npm reads the app’s setup file and downloads the pieces the app needs to work.

On macOS:

1. Go to nodejs.org/en/download.
2. Download and install macOS Installer (.pkg).
3. Open Terminal.
4. Check that Node.js and npm are available:

$ node --version
$ npm --version

On Windows:

1. Go to nodejs.org/en/download.
2. Download and install Windows Installer (.msi).
3. Open the Start menu, search for PowerShell, and open it.
4. Check that Node.js and npm are available:

PS> node --version
PS> npm --version

If both commands print version numbers, continue.

3. Create a Railway Account

Railway is the service that will host your app online. Create or sign into a Railway account at railway.com. The Railway free trial should work for the sprint and includes credits for up to 30 days. If you want the app to keep running after the trial, upgrade to the Hobby plan, which is $5 per month and includes $5 of usage.

The Railway command-line tool lets you send the app from your computer to Railway. It is included in this kit and will be installed when you run npm install in Step 5.

4. Create and Add the Gemini API Key

1. Create or sign into a Google account. A personal Google account may be simpler if a school or work account blocks API key creation.
2. Go directly to the Google AI Studio API Keys page: aistudio.google.com/app/apikey.
3. Click Create API key. If Google asks you to choose a Cloud project, choose the option to create the key in a new project.
4. Copy the key when it appears and keep it private. It will look like a long string of letters and numbers, for example AIzaSyFAKEKeyForClassDemo1234567890ABCD.
5. Open local.env and paste your key where you see your_real_key_here in the line GEMINI_API_KEY=your_real_key_here. You will also add this key to Railway during deployment.

5. Install Dependencies

In Terminal or PowerShell, move into the app kit folder. The exact folder name may differ on your computer.

On macOS:

$ cd ~/Desktop/myapp
$ npm install

On Windows PowerShell:

PS> cd "$env:USERPROFILE\Desktop\myapp"
PS> npm install

This installs the software pieces the starter app needs, including the Railway command-line tool for this project. It will create a folder called node_modules. That folder is not included in the kit, and you should not edit or share it.

Phase 2: Prototype Locally

1. Define First Version

Open AppPlan.md and fill in the app idea section: use case, intended user, user input, model output, model approach, and whether the app needs source material or a dataset. This is your direct instruction to Cowork/Codex about what to build. The purpose is not to design the perfect app on the first try. The purpose is to get something basic working; once the simple version runs, you can iterate with Cowork/Codex to improve the prompt, interface, examples, and source material.

2. Customize with Cowork/Codex

The purpose of this step is to ask Cowork/Codex to turn your app plan into a first working version that you can test locally. You do not need to finish the whole product here. Get the basic version working, then keep building later.

Start with the following clear instruction:

> Read AppPlan.md and App_Development_Kit.html. Before editing, summarize the app purpose, required layout, colors, inputs, outputs, system prompt requirements, and model behavior from AppPlan.md. Then build the first working version using the files already in this folder. Treat the design notes in AppPlan.md as requirements. Create a clearly labeled, editable system prompt in the code for any LLM or RAG app. Keep it simple, make sure it runs locally at http://localhost:3000, and keep it deployable on Railway.

3. Run Locally

On macOS, clear anything still using port 3000, then start the app:

$ lsof -ti tcp:3000 | xargs kill
$ npm start

On Windows PowerShell, start the app:

PS> npm start

Open the local address shown in the terminal, usually http://localhost:3000. Test the starter app.

Important: this command keeps running because it is keeping the local app alive. When you are done testing, return to the terminal and press Ctrl-C.

Phase 3: Deploy on Railway

1. Log Into Railway

$ npm run railway -- login

The login command opens a browser window. After logging in, return to the terminal.

2. Check the Railway Account

$ npm run railway -- whoami

This confirms which Railway account is connected in your terminal.

3. Create Railway Project

Run this from inside the project folder.

$ npm run railway -- init

If Railway asks questions, choose your workspace or account, create a new project, and name it myapp or another short name. This creates the Railway project, but it may not create the deployable service yet.

4. Create the Service

Deploy once so Railway can create the web service for this folder.

$ npm run railway -- up

When the deployment finishes, return to Terminal or PowerShell and press Ctrl-C so you can enter the next command.

5. Link the Service

Link your local folder to the service Railway just created.

$ npm run railway -- service link

Select the service with your project name, usually myapp.

$ npm run railway -- status

In the status output, the linked service should no longer say None.

6. Add Gemini Key

The local.env file works only on your computer. Railway needs its own copy of the key. Set these variables only after the service exists and is linked. If Railway says Project has no services, go back to Create the Service and Link the Service before trying this again.

$ npm run railway -- variable set GEMINI_API_KEY="YOUR_KEY_HERE"

$ npm run railway -- variable set GEMINI_MODEL="gemini-2.5-flash"

7. Redeploy

$ npm run railway -- up

Redeploy after setting variables so the running app can use the Gemini key.

8. Create a Public URL

$ npm run railway -- domain

Railway will give you a free Railway-provided URL. Open that URL in your browser to test the deployed app.

9. Set a Custom URL

After the site is working, go to railway.com and open the dashboard. Open your project, click the deployed service, then go to Settings > Networking > Public Networking. Edit the default Railway URL to a new one.

Phase 4: Iterate

1. Pick One Improvement

Once the first deployed version works, choose one improvement at a time. Good next steps include a clearer app name, a cleaner visual design, a better sample question, a more specific system prompt, a new input field, or a more useful answer format.

2. Ask Cowork/Codex for the Change

Be specific about what should change and what should stay the same. For example, a design prompt might look like:

> Redesign the app as a centered, single-column page. Keep the same form fields, submit button, model call, and Railway deployment setup. Use a white background, one orange accent color for buttons and headings, generous spacing, and a professional style for MBA students. Do not add new features yet. After editing, tell me exactly which files changed and how to test the design locally.

A functionality prompt might look like:

> Add a saved answers section below the model response. Each time the user submits a question, save the question and answer in a simple list on the page. Add a Clear saved answers button. Keep the data only in the browser for this session; do not add accounts, databases, or login. Keep the existing Railway deployment setup unchanged. After editing, explain how to test this feature locally.

3. Test and Redeploy

After each change, run the app locally.

$ npm start

Test it locally, then deploy again on Railway.

$ npm run railway -- up

If You Get Stuck

Good luck and happy building.