# Getting Started with Development

This guide helps you set up your local development environment for both the TMI server (Go) and TMI web application (Angular/TypeScript).

## Overview

TMI consists of two main components:
- **TMI Server** - Go-based RESTful API server with WebSocket support
- **TMI-UX** - Angular-based web application for threat modeling

## Prerequisites

### Required Tools

#### For TMI Server (Go)
- **Go 1.24+** - [Download](https://golang.org/dl/)
- **Docker Desktop** - For PostgreSQL and Redis containers
- **Make** - Build automation (pre-installed on macOS/Linux)

#### For TMI-UX (Angular)
- **Node.js** - Latest LTS version (20.19.2 recommended) - [Download](https://nodejs.org/)
- **pnpm** - Fast, disk space efficient package manager - [Install](https://pnpm.io/installation)

### Optional Tools
- **Newman** - For API testing - `npm install -g newman`
- **Docker Scout** - Container vulnerability scanning
- **golangci-lint** - Go code linting

## Quick Start

### Option 1: Server Only (Go Backend)

```bash
# Clone the repository
git clone https://github.com/ericfitz/tmi.git
cd tmi

# Start development environment (database + Redis + server)
make start-dev

# Server will be running on http://localhost:8080
```

The `make start-dev` command automatically:
1. Starts PostgreSQL container on port 5432
2. Starts Redis container on port 6379
3. Waits for database to be ready
4. Runs database migrations
5. Starts the TMI server on port 8080

### Option 2: Full Stack (Server + Web App)

**Terminal 1 - Start Server:**
```bash
cd tmi
make start-dev
```

**Terminal 2 - Start Web Application:**
```bash
cd tmi-ux
pnpm install
pnpm run dev
```

The web application will be available at http://localhost:4200

## TMI Server Setup (Detailed)

### 1. Environment Configuration

TMI uses YAML configuration files. The development config is auto-generated:

```bash
# Generated automatically on first run
config-development.yml
```

Configuration includes:
- Database connection (PostgreSQL)
- Redis connection (caching/sessions)
- OAuth provider credentials
- Server settings (ports, timeouts, TLS)

### 2. Database Setup

Development uses Docker containers for PostgreSQL:

```bash
# Start PostgreSQL only
make start-database

# Wait for database to be ready
make wait-database

# Run migrations
make migrate-database

# Check migration status
make check-database
```

**Connection details:**
- Host: `localhost:5432`
- User: `tmi_dev`
- Password: `dev123`
- Database: `tmi_dev`

### 3. OAuth Provider Configuration

For authentication, configure OAuth providers in `config-development.yml`:

#### Google OAuth Setup

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create OAuth 2.0 credentials
3. Add redirect URI: `http://localhost:8080/oauth2/callback`
4. Update `config-development.yml`:

```yaml
oauth:
  providers:
    - name: google
      client_id: YOUR_CLIENT_ID.apps.googleusercontent.com
      client_secret: YOUR_CLIENT_SECRET
      authorize_url: https://accounts.google.com/o/oauth2/v2/auth
      token_url: https://oauth2.googleapis.com/token
      userinfo_url: https://www.googleapis.com/oauth2/v2/userinfo
```

#### Test OAuth Provider

For development, you can use the built-in test provider (no configuration needed):

```bash
# Access test OAuth
curl "http://localhost:8080/oauth2/authorize?idp=test"
```

The test provider creates random users: `testuser-12345678@test.tmi`

For predictable test users, use login hints:

```bash
# Create specific test user 'alice@test.tmi'
curl "http://localhost:8080/oauth2/authorize?idp=test&login_hint=alice"
```

### 4. Available Make Commands

```bash
# Development
make start-dev          # Start complete dev environment
make start-dev-0        # Start on 0.0.0.0 (accessible from network)
make clean-dev          # Clean up everything

# Building
make build-server       # Build server binary
make build-migrate      # Build migration tool
make clean-build        # Clean build artifacts

# Database
make start-database     # Start PostgreSQL container
make stop-database      # Stop PostgreSQL container
make clean-database     # Remove container and data
make reset-database     # Drop and recreate database (DESTRUCTIVE)
make migrate-database   # Run migrations

# Testing
make test-unit          # Run Go unit tests
make test-integration   # Run integration tests with full setup
make test-api           # Run Postman/Newman API tests
make test-coverage      # Generate coverage reports

# Services
make start-redis        # Start Redis container
make stop-redis         # Stop Redis container
make status             # Check status of all services

# Server control
make start-server       # Start server
make stop-server        # Stop server
```

### 5. Verify Server Installation

```bash
# Check server status
curl http://localhost:8080/

# Expected response
{
  "api": {
    "version": "1.0",
    "build": "0.9.0"
  },
  "service": {
    "name": "TMI API Server",
    "build": "0.9.0-abc123"
  }
}
```

## TMI-UX Setup (Detailed)

### 1. Install Dependencies

```bash
cd tmi-ux
pnpm install
```

### 2. Environment Configuration

TMI-UX supports multiple environment configurations:

```bash
# Default development (uses environment.ts)
pnpm run dev

# Staging environment
pnpm run dev:staging

# Test environment
pnpm run dev:test

# Local environment (custom)
pnpm run dev:local
```

#### Creating Custom Environment

1. Copy example: `cp src/environments/environment.example.ts src/environments/environment.local.ts`
2. Configure `environment.local.ts`:

```typescript
export const environment = {
  production: false,
  logLevel: 'DEBUG',
  apiUrl: 'http://localhost:8080',
  authTokenExpiryMinutes: 1440, // 24 hours for dev
  operatorName: 'TMI Development',
  operatorContact: 'dev@example.com'
};
```

3. Update `angular.json` to add configuration:

```json
"configurations": {
  "local": {
    "fileReplacements": [
      {
        "replace": "src/environments/environment.ts",
        "with": "src/environments/environment.local.ts"
      }
    ]
  }
}
```

### 3. Available pnpm Scripts

```bash
# Development
pnpm run dev              # Start dev server on localhost:4200
pnpm run dev:0            # Start on 0.0.0.0 (accessible from network)
pnpm run dev:staging      # Start with staging config
pnpm run dev:test         # Start with test config

# Building
pnpm run build            # Development build
pnpm run build:prod       # Production build
pnpm run build:staging    # Staging build

# Testing
pnpm run test             # Run Vitest unit tests
pnpm run test:watch       # Run tests in watch mode
pnpm run test:coverage    # Generate coverage report
pnpm run test:e2e         # Run Cypress E2E tests
pnpm run test:e2e:open    # Open Cypress GUI

# Code Quality
pnpm run lint             # Lint TypeScript/HTML files
pnpm run lint:scss        # Lint SCSS files
pnpm run lint:all         # Lint everything
pnpm run format           # Format code with Prettier
pnpm run format:check     # Check formatting

# Validation
pnpm run validate-json        # Validate JSON files
pnpm run validate-json:i18n   # Validate i18n files
pnpm run validate-jsonc       # Validate JSONC files
```

### 4. Verify Web Application

```bash
# Start dev server
pnpm run dev

# Open browser to http://localhost:4200
# You should see the TMI login page
```

## Development Workflow

### 1. Server Development

```bash
# Terminal 1: Start services
cd tmi
make start-dev

# Terminal 2: Run tests on code changes
make test-unit

# Terminal 3: Watch logs
tail -f logs/server.log
```

### 2. Web Application Development

```bash
# Terminal 1: Start server
cd tmi
make start-dev

# Terminal 2: Start web app
cd tmi-ux
pnpm run dev

# Hot reload is enabled - changes reflect immediately
```

### 3. Full Stack Testing

```bash
# Terminal 1: Start server
cd tmi
make start-dev

# Terminal 2: Start web app
cd tmi-ux
pnpm run dev

# Terminal 3: Run E2E tests
cd tmi-ux
pnpm run test:e2e
```

## Project Structure

### TMI Server (Go)

```
tmi/
├── api/                  # API handlers and types
├── auth/                 # Authentication services
├── cmd/
│   ├── server/          # Server entry point
│   └── migrate/         # Database migration tool
├── internal/            # Internal packages
├── docs/
│   ├── developer/       # Developer documentation
│   ├── operator/        # Operations documentation
│   └── reference/       # API specs, architecture
├── postman/             # API test collections
├── scripts/             # Build and utility scripts
├── config-development.yml  # Dev configuration
└── Makefile            # Build automation
```

### TMI-UX (Angular)

```
tmi-ux/
├── src/
│   ├── app/
│   │   ├── core/        # Core services, guards
│   │   ├── pages/       # Page components
│   │   ├── shared/      # Shared components
│   │   └── models/      # TypeScript models
│   ├── assets/          # Static assets, i18n
│   └── environments/    # Environment configs
├── cypress/             # E2E tests
├── docs/
│   ├── developer/       # Developer docs
│   └── reference/       # Architecture docs
├── scripts/             # Build scripts
└── package.json         # Dependencies and scripts
```

## Common Development Tasks

### Adding a New API Endpoint (Server)

1. Define endpoint in OpenAPI spec: `docs/reference/apis/tmi-openapi.json`
2. Generate API code: `make generate-api`
3. Implement handler in `api/`
4. Add database operations if needed
5. Write unit tests
6. Write integration tests in `api/*_integration_test.go`
7. Add Postman tests in `postman/`

### Adding a New UI Feature (Web App)

1. Generate component: `pnpm exec ng generate component pages/my-feature`
2. Add to routing: `src/app/app.routes.ts`
3. Create service if needed: `pnpm exec ng generate service core/services/my-service`
4. Add i18n keys: `src/assets/i18n/en-US.json`
5. Write unit tests: `*.spec.ts`
6. Write E2E tests: `cypress/e2e/*.cy.ts`

## Troubleshooting

### Server Won't Start

```bash
# Check if port 8080 is in use
lsof -ti :8080

# Kill process on port
make clean-dev

# Check database connection
make start-database
make wait-database
docker exec tmi-postgresql pg_isready -U tmi_dev
```

### Database Migration Issues

```bash
# Check migration status
make check-database

# Reset database (DESTRUCTIVE - deletes all data)
make reset-database

# Manual migration
cd cmd/migrate
go run main.go --env ../../.env.dev up
```

### Web App Won't Connect to API

1. Check server is running: `curl http://localhost:8080/`
2. Verify `apiUrl` in environment file
3. Check browser console for CORS errors
4. Ensure you're authenticated (valid JWT token)

### OAuth Not Working

1. Check OAuth config in `config-development.yml`
2. Verify redirect URI matches OAuth provider
3. Use test provider for development: `?idp=test`
4. Check server logs: `tail -f logs/server.log`

## Next Steps

- [Architecture and Design](Architecture-and-Design.md) - Understand system architecture
- [API Integration](API-Integration.md) - Learn to integrate with TMI APIs
- [Testing](Testing.md) - Testing strategies and tools
- [Contributing](Contributing.md) - Contribution guidelines

## Getting Help

- **Documentation**: See `/docs` in both repositories
- **Issues**: https://github.com/ericfitz/tmi/issues
- **API Reference**: http://localhost:8080/ (when server is running)
- **OpenAPI Spec**: `docs/reference/apis/tmi-openapi.json`