Skip to content

Getting Started with LBS Foundry

Welcome to the LBS Foundry development team! This guide will get you up and running with the codebase in no time.

Prerequisites

Before you begin, ensure you have the following tools installed:

Required Tools

Tip: See prerequisites.md for detailed installation instructions.

Quick Setup (5 minutes)

1. Clone the Repository

git clone https://github.com/luckboxstudios/LBS.Foundry.git
cd LBS.Foundry

2. Setup Backend

# Restore dependencies
dotnet restore LBS.slnx

# Build the solution
dotnet build LBS.slnx

# Run unit tests to verify setup (xUnit v3 — use `dotnet run`, not `dotnet test`)
dotnet run --project src/Tests/LBS.UnitTests/LBS.UnitTests.csproj

3. Setup Frontend (foundry-web)

The frontend uses a local TypeScript SDK that must be built before running.

# From repo root - install dependencies and establish workspace links
pnpm install

# Build .NET, generate SDK types, and compile TypeScript SDK
pnpm sdk:refresh

This builds the @luckboxstudios/foundry-sdk package that foundry-web depends on.

Note: You must run pnpm sdk:refresh whenever C# contracts change, or after a fresh clone.

4. Configure Database

There is no separate migration step. Marten applies the schema automatically on application startup (ApplyAllDatabaseChangesOnStartup() with AutoCreate.All), so the schema is created/updated when a host such as the API starts. Just ensure PostgreSQL is running and the connection string is configured before starting the development environment below.

5. Start Development Environment

# Start the Aspire development host (includes all services)
dotnet run --project src/Aspire/LBS.AspireHost/LBS.AspireHost.csproj

That's it! Your development environment should now be running.

Accessing the Applications

Once started, you can access:

  • Aspire Dashboard: http://localhost:15000 - Service monitoring
  • API: http://localhost:5000 - Backend API
  • Frontend: http://localhost:5173 - foundry-web (SvelteKit)
  • API Docs: http://localhost:5000/swagger - OpenAPI documentation

What's Next?

Development Workflow

Daily Development

# Start development environment
dotnet run --project src/Aspire/LBS.AspireHost/LBS.AspireHost.csproj

# In a separate terminal - Frontend development (from repo root)
pnpm web:dev

# Run tests before committing (xUnit v3 — use `dotnet run`, not `dotnet test`)
dotnet run --project src/Tests/LBS.UnitTests/LBS.UnitTests.csproj

Making Changes

  1. Create a feature branch: git checkout -b feature/your-feature
  2. Make your changes following our coding standards
  3. Run tests: dotnet run --project src/Tests/LBS.UnitTests/LBS.UnitTests.csproj
  4. Commit changes: Use conventional commits
  5. Create pull request

Authentication Setup

The system supports two authentication methods:

1. Clerk Authentication (Human Users)

  • Used in the frontend application
  • JWT-based authentication
  • User management handled by Clerk

2. Basic Authentication (Service Accounts)

Testing Authentication: For a complete guide on testing authentication end-to-end, see Authentication Testing Guide.

Key Concepts to Understand

Event Sourcing

  • All state changes are stored as events
  • Complete audit trail and replay capability
  • See Event Sourcing Guide

CQRS (Command Query Responsibility Segregation)

Role-based Authorization

  • Commands and queries can require specific roles
  • Automatic authorization enforcement
  • See Security Guide

Troubleshooting

Common Issues

Build Errors 

# Clean and rebuild
dotnet clean LBS.slnx
dotnet build LBS.slnx

Database Issues 

# Recreate the database, then start a host (e.g. LBS.Api) — Marten applies the
# schema automatically on startup via ApplyAllDatabaseChangesOnStartup().
dropdb lbs_foundry_dev
createdb lbs_foundry_dev
dotnet run --project src/Apps/LBS.Api/LBS.Api.csproj

Frontend Issues 

# Rebuild the SDK (most common fix)
pnpm sdk:refresh

# Or clear and reinstall everything
rm -rf node_modules sdk/typescript/node_modules src/Apps/foundry-web/node_modules
pnpm install
pnpm sdk:refresh

Complete Troubleshooting Guide

Getting Help

Welcome to the Team!

You're now ready to start contributing to LBS Foundry! Here are some good first tasks:

  1. Explore the codebase - Look at existing commands, queries, and aggregates
  2. Run the test suite - Understand how we test our code
  3. Try making a small change - Add a simple query or command
  4. Review our coding standards - Learn our conventions

Happy coding!