Capstone Project

An AI-assisted web application built as a capstone project. The app combines a modern web frontend with backend services and AI integrations to deliver an interactive user experience.

Table of Contents

• Features
• Tech Stack
• Prerequisites
• Setup
• Environment Variables
• Running the Application
• Project Structure
• Development
• Troubleshooting
• License

Features

• Web-based UI for interacting with AI-assisted workflows
• Configurable AI provider integration (API key driven)
• Local development workflow with hot reload
• Production-ready build and deployment path

Note: This repository is in early development. Application source code and scripts will be added as the capstone progresses. The setup steps below cover both the current repository state and the expected workflow once the app scaffold is in place.

Tech Stack

Layer	Technology (planned)
Runtime	Node.js (LTS)
Package manager	npm
Frontend	React (or Next.js)
Backend	Node.js API
AI	Provider API (e.g. OpenAI)

Update this table as you finalize your stack.

Prerequisites

Install the following before setting up the project:

Tool	Minimum version	Verify with
Git	2.x	git --version
Node.js	20.x LTS	node --version
npm	10.x	npm --version

Optional but recommended:

• Cursor or VS Code — IDE with AI-assisted development support
• An AI provider account — for API keys used during development (OpenAI, Anthropic, Azure OpenAI, etc.)

Setup

Follow these steps from a clean machine to get the project ready for development.

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/capstone-project.git
cd capstone-project

Replace YOUR_USERNAME with your GitHub username or organization once the remote is published.

If you already have the repo locally, pull the latest changes before installing dependencies:

git pull origin master

2. Use the correct Node.js version

If you use nvm (macOS/Linux) or nvm-windows:

nvm install 20
nvm use 20

Confirm versions:

node --version   # should print v20.x.x
npm --version    # should print 10.x.x

3. Install dependencies

Once a package.json is added to the repository:

npm install

This installs frontend, backend, and shared dependencies into node_modules/ (already listed in .gitignore).

If the project uses separate client and server folders, install in each:

# Example for a monorepo-style layout
cd client && npm install && cd ..
cd server && npm install && cd ..

4. Configure environment variables

Copy the example environment file and fill in your values:

cp .env.example .env

See Environment Variables for required keys. Never commit .env or real API keys to Git.

5. Verify the installation

After application code is present, confirm dependencies and config:

npm run build    # optional: ensure the project compiles
npm test         # optional: run the test suite

Environment Variables

Create a .env file in the project root (and add .env to .gitignore if not already present). Example variables for an AI-assisted web app:

Variable	Required	Description
PORT	No	Local server port (default: 3000)
NODE_ENV	No	development or production
AI_API_KEY	Yes*	API key for your AI provider
AI_API_BASE_URL	No	Override base URL for custom or proxy endpoints
DATABASE_URL	No	Connection string if using a database

* Required once AI features are implemented.

Example .env.example (commit this file, not .env):

PORT=3000
NODE_ENV=development
AI_API_KEY=your_api_key_here
# AI_API_BASE_URL=https://api.openai.com/v1
# DATABASE_URL=

Running the Application

When scripts are defined in package.json, use:

# Start development server (hot reload)
npm run dev

# Start production build locally
npm run build
npm start

Typical URLs after startup:

Service	URL
Web app	http://localhost:3000
API	http://localhost:3000/api (or separate port)

Adjust ports if your configuration differs.

Project Structure

Expected layout as the capstone grows:

capstone-project/
├── client/          # Frontend application (optional split)
├── server/          # Backend API (optional split)
├── public/          # Static assets
├── src/             # Application source (if single-package layout)
├── .env.example     # Committed template for environment variables
├── .gitignore
├── LICENSE
├── package.json
└── README.md

Current repository contents: documentation, license, and Git configuration only.

Development

Recommended workflow

1. Create a feature branch: git checkout -b feature/your-feature-name
2. Make changes and test locally with npm run dev
3. Run lint/tests before committing: npm run lint and npm test
4. Commit with clear messages (e.g. feat: add chat UI, fix: handle empty API response)
5. Open a pull request for review

Code conventions

Project-specific rules live in .cursorrules. Keep naming consistent, avoid committing secrets, and document non-obvious behavior in code comments sparingly.

Troubleshooting

Issue	What to try
command not found: node or npm	Install Node.js LTS and restart your terminal
EACCES or permission errors on npm install	Avoid sudo; fix npm prefix or use nvm
Port already in use	Change PORT in .env or stop the process using that port
AI requests fail with 401/403	Check AI_API_KEY in .env; ensure the key is valid and has quota
Empty page after npm run dev	Confirm you are in the repo root; check terminal for build errors

On Windows, run commands in PowerShell or Git Bash from the project root.

License

This project is licensed under the MIT License — see LICENSE for details.