Browser (http://localhost:8080)
↕ HTTP + SignalR
ASP.NET Core API (http://localhost:5069)
↕ Entity Framework Core
SQL Server Express (localhost\SQLEXPRESS → BuildTrackDB)
Time required: ~30 minutes on first install, ~2 minutes on subsequent starts.
Skip any step where the tool is already installed.
- Go to: https://dotnet.microsoft.com/download/dotnet/8.0
- Download .NET 8.0 SDK (not Runtime) for Windows x64
- Run the installer, accept defaults
- Open a new PowerShell or Command Prompt window and verify:
dotnet --version
# Must show 8.x.x (e.g. 8.0.404)- Go to: https://www.microsoft.com/en-us/sql-server/sql-server-downloads
- Scroll to SQL Server 2022 Express → click Download now
- Run the installer → choose Basic installation type
- Accept the license → click Install
- When complete, note the Instance name shown — it will be:
Server Name: localhost\SQLEXPRESS - Click Close (you do NOT need SSMS for this guide)
Verify SQL Server is running:
Get-Service -Name "MSSQL*" # Should show Status = Running for MSSQL$SQLEXPRESSIf it shows Stopped:
Start-Service "MSSQL$SQLEXPRESS"
Open PowerShell and run:
dotnet tool install --global dotnet-efVerify:
dotnet ef --version
# Should show 8.x.xIf already installed but on an older version:
dotnet tool update --global dotnet-ef- Go to: https://nodejs.org
- Download LTS version
- Run the installer, accept defaults
- Verify:
node --version # 18.x.x or higher
npm --version # 9.x.x or higherOpen VS Code, press Ctrl+Shift+X, search and install:
| Extension | Publisher | Purpose |
|---|---|---|
| C# Dev Kit | Microsoft | C# IntelliSense, run/debug |
| REST Client | Humao | Test API endpoints from VS Code |
Open PowerShell in the project root folder and run:
sqlcmd -S "localhost\SQLEXPRESS" -E -Q "CREATE DATABASE BuildTrackDB"Verify it was created:
sqlcmd -S "localhost\SQLEXPRESS" -E -Q "SELECT name FROM sys.databases WHERE name = 'BuildTrackDB'"You should see BuildTrackDB in the output.
If sqlcmd is not found: Add SQL Server tools to PATH:
$env:PATH += ";C:\Program Files\Microsoft SQL Server\Client SDK\ODBC\170\Tools\Binn"Or use the full path:
& "C:\Program Files\Microsoft SQL Server\160\Tools\Binn\SQLCMD.EXE" -S "localhost\SQLEXPRESS" -E -Q "CREATE DATABASE BuildTrackDB"
# Navigate to the backend project
cd backend\BuildTrack.API
# Create the initial migration (only needed once)
dotnet ef migrations add InitialCreate --output-dir Data\Migrations
# Apply the migration to create all tables
dotnet ef database updateExpected output ends with:
Done.
Note: The API also runs migrations automatically on startup in Development mode, so this step is optional — but running it manually lets you catch errors early.
This creates your first login account:
# Still in the project root (go back up from backend/BuildTrack.API if needed)
cd ..\..
sqlcmd -S "localhost\SQLEXPRESS" -d "BuildTrackDB" -E -i "database-scripts\002_seed_admin.sql"Expected output:
Admin user seeded: admin@buildtrack.com / Admin@123456
Default login credentials:
- Email:
admin@buildtrack.com- Password:
Admin@123456- Change this password after your first login!
Adds 10 sample SKUs and 2 sample projects to explore the app:
sqlcmd -S "localhost\SQLEXPRESS" -d "BuildTrackDB" -E -i "database-scripts\003_seed_sample_data.sql"Open backend/BuildTrack.API/appsettings.json and confirm:
"ConnectionStrings": {
"DefaultConnection": "Server=localhost\\SQLEXPRESS;Database=BuildTrackDB;Trusted_Connection=True;MultipleActiveResultSets=true;TrustServerCertificate=True"
}If your SQL Server instance has a different name, update
localhost\\SQLEXPRESSto match. To check your instance name:sqlcmd -S "localhost\SQLEXPRESS" -E -Q "SELECT @@SERVERNAME"
Open backend/BuildTrack.API/appsettings.Development.json:
"Jwt": {
"Secret": "dev-secret-key-change-in-production-must-be-32-chars",
"Issuer": "BuildTrack.API",
"Audience": "BuildTrack.Frontend"
}The default development secret is fine for local use. For production, replace it with a strong random key:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"cd backend\BuildTrack.API
dotnet restoreFirst run downloads all packages (~30 seconds). Subsequent runs are instant.
dotnet buildExpected output:
Build succeeded.
0 Warning(s)
0 Error(s)
If you see errors, the most common fixes:
dotnet restorewas not run first- .NET SDK version is not 8.x — check with
dotnet --version
dotnet runWait for this output:
info: Microsoft.Hosting.Lifetime[14]
Now listening on: http://localhost:5069
info: Microsoft.Hosting.Lifetime[0]
Application started. Press Ctrl+C to stop.
On first startup, it will also run any pending EF Core migrations automatically.
Open your browser and go to:
http://localhost:5069/swagger
You should see the BuildTrack API Swagger documentation page listing all endpoints.
Test a login from Swagger:
- Click on
POST /api/auth/login→ Try it out - Paste this body:
{ "loginId": "admin@buildtrack.com", "password": "Admin@123456" } - Click Execute
- You should get a
200 OKresponse withaccessTokenandrefreshToken
✅ Backend is working!
In VS Code: Ctrl+Shift+`` or open a new PowerShell window.
Navigate to the project root (where package.json lives):
cd C:\Users\elopez24\Documents\stockwell-buildnpm installAlso install the SignalR client for real-time notifications:
npm install @microsoft/signalrOpen .env in the project root and confirm it contains:
VITE_API_BASE_URL=http://localhost:5069This tells the frontend where to find the backend API. If your backend runs on a different port, update this value.
npm run devWait for:
VITE v7.x.x ready in xxx ms
➜ Local: http://localhost:8080/
Go to: http://localhost:8080
You should see the BuildTrack login page.
Log in with:
- Email:
admin@buildtrack.com - Password:
Admin@123456
After login you should land on the Dashboard.
✅ Full stack is running!
After the initial setup, starting the app requires only two commands in two terminals:
cd backend\BuildTrack.API
dotnet runcd C:\Users\elopez24\Documents\stockwell-build
npm run dev| URL | Purpose |
|---|---|
| http://localhost:8080 | Frontend app (login here) |
| http://localhost:5069/swagger | Backend API docs + interactive testing |
| http://localhost:5069/api/auth/me | Check if you're authenticated |
Run through this checklist after starting both services:
- Backend terminal shows
Now listening on: http://localhost:5069 - Frontend terminal shows
Local: http://localhost:8080/ - http://localhost:5069/swagger loads without error
- http://localhost:8080 shows the login page
- Login with
admin@buildtrack.com/Admin@123456succeeds - Dashboard loads with stats and recent orders
- No red errors in the browser console (
F12→ Console tab)
# Check if service is running
Get-Service "MSSQL$SQLEXPRESS"
# Start it if stopped
Start-Service "MSSQL$SQLEXPRESS"
# Test the connection directly
sqlcmd -S "localhost\SQLEXPRESS" -E -Q "SELECT @@VERSION"Common causes:
- SQL Server service stopped → start it as shown above
- Wrong instance name → check with
sqlcmd -Lto list local instances - Named Pipes disabled → open SQL Server Configuration Manager → enable TCP/IP and Named Pipes for SQLEXPRESS
The database doesn't exist or migrations haven't run:
# Create DB manually
sqlcmd -S "localhost\SQLEXPRESS" -E -Q "CREATE DATABASE BuildTrackDB"
# Re-run migrations
cd backend\BuildTrack.API
dotnet ef database update# Find what's using port 5069
netstat -ano | findstr :5069
# Kill the process (replace 1234 with the PID shown)
taskkill /PID 1234 /FOr change the port in backend/BuildTrack.API/Properties/launchSettings.json.
- Confirm the backend is running: open http://localhost:5069/swagger
- Check
.envhas the correct port:VITE_API_BASE_URL=http://localhost:5069 - Restart the frontend after changing
.env:# Ctrl+C to stop, then: npm run dev
The admin seed script may not have run, or BCrypt hash is wrong:
# Re-run the seed script
sqlcmd -S "localhost\SQLEXPRESS" -d "BuildTrackDB" -E -i "database-scripts\002_seed_admin.sql"If the record already exists, delete it first and re-seed:
sqlcmd -S "localhost\SQLEXPRESS" -d "BuildTrackDB" -E -Q "DELETE FROM Profiles WHERE Email = 'admin@buildtrack.com'"
sqlcmd -S "localhost\SQLEXPRESS" -d "BuildTrackDB" -E -i "database-scripts\002_seed_admin.sql"dotnet tool install --global dotnet-ef
# Close and reopen your terminal, then try againIf dotnet ef migrations add fails because a migration already exists:
# Remove the broken migration
dotnet ef migrations remove
# Re-create it
dotnet ef migrations add InitialCreate --output-dir Data\Migrations
# Apply
dotnet ef database updatenpm install @microsoft/signalr
# Restart the frontendIf SignalR is installed but still not connecting, check the browser console for the specific error.
stockwell-build/
│
├── backend/BuildTrack.API/ ← ASP.NET Core 8 Web API
│ ├── Controllers/ ← REST endpoints (Auth, Orders, Projects...)
│ ├── Services/ ← Business logic
│ ├── Models/Entities/ ← Database entity classes
│ ├── DTOs/ ← API request/response shapes
│ ├── Data/AppDbContext.cs ← EF Core database context
│ ├── Data/Migrations/ ← Auto-generated DB migration files
│ ├── Hubs/NotificationHub.cs ← SignalR real-time notifications
│ ├── Middleware/ ← Global error handling
│ ├── Program.cs ← App startup and DI configuration
│ ├── appsettings.json ← Production config (DB, JWT, CORS)
│ └── appsettings.Development.json ← Dev overrides (longer tokens, verbose logging)
│
├── database-scripts/
│ ├── 001_create_database.sql ← Creates BuildTrackDB
│ ├── 002_seed_admin.sql ← Creates admin@buildtrack.com account
│ └── 003_seed_sample_data.sql ← Sample SKUs and projects
│
├── src/ ← React + TypeScript frontend
│ ├── lib/apiClient.ts ← All REST API calls + JWT token management
│ ├── contexts/AuthContext.tsx ← Login state, roles, permissions
│ ├── hooks/useNotifications.ts ← Real-time notifications (SignalR + fallback)
│ ├── lib/activityLogger.ts ← Sends audit logs to backend
│ ├── lib/notificationService.ts ← In-app notification helpers
│ ├── pages/ ← Page components (Dashboard, Orders, etc.)
│ └── components/ ← Reusable UI components
│
├── .env ← Frontend: VITE_API_BASE_URL=http://localhost:5069
├── package.json ← Frontend npm dependencies
├── vite.config.ts ← Dev server config (port 8080)
│
├── QUICKSTART.md ← This file
└── MIGRATION_GUIDE.md ← Supabase → .NET migration details
| Item | Value |
|---|---|
| Admin email | admin@buildtrack.com |
| Admin password | Admin@123456 |
| Frontend URL | http://localhost:8080 |
| Backend API URL | http://localhost:5069 |
| Swagger URL | http://localhost:5069/swagger |
| Database server | localhost\SQLEXPRESS |
| Database name | BuildTrackDB |
| JWT expiry (dev) | 8 hours |
| Refresh token expiry | 30 days |
Good luck! If something breaks, start with the Troubleshooting section in Part 8.