# 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` - **Grype** - Container vulnerability scanning - `brew install grype` - **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. Copy `config-example.yml` to `config-development.yml` on first setup: ```bash # Copy example config and customize cp config-example.yml 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 ``` #### TMI Test OAuth Provider For development, you can use the built-in TMI provider (no configuration needed): ```bash # Access TMI OAuth provider (creates random user) curl "http://localhost:8080/oauth2/authorize?idp=tmi" ``` The TMI provider creates users like: `testuser-12345678@tmi.local` For predictable test users, use login hints: ```bash # Create specific test user 'alice@tmi.local' curl "http://localhost:8080/oauth2/authorize?idp=tmi&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 ``` ## File Naming Conventions This section outlines the file naming conventions for the TMI-UX project. ### File Naming Standards | Type | Pattern | Example | Usage | |------|---------|---------|-------| | Components | `*.component.ts` | `user-preferences-dialog.component.ts` | All Angular components | | Services | `*.service.ts` | `threat-model.service.ts` | All @Injectable() classes that provide business logic | | Guards | `*.guard.ts` | `auth.guard.ts` | All route guards | | Interceptors | `*.interceptor.ts` | `jwt.interceptor.ts` | All HTTP interceptors | | Resolvers | `*.resolver.ts` | `threat-model.resolver.ts` | All route resolvers | | Models | `*.model.ts` | `threat-model.model.ts` | Data models and interface definitions | | Interfaces | `*.interface.ts` | `auth.interface.ts` | Interface definitions (alternative to .model.ts) | | Types | `*.types.ts` | `websocket-message.types.ts` | Type definitions and type aliases | | Constants | `*-constants.ts` | `styling-constants.ts` | Constant values and configuration objects | | Utilities | `*.util.ts` or `*.utils.ts` | `cell-normalization.util.ts` | Utility functions and helper methods | | Adapters | `*.adapter.ts` | `infra-x6-graph.adapter.ts` | Infrastructure adapters for external libraries | | Tests | `*.spec.ts` | `auth.service.spec.ts` | Unit tests | | Routes | `*.routes.ts` | `tm.routes.ts` | Route configuration files | | State | `*.state.ts` | `dfd.state.ts` | State management files | | Barrel Exports | `index.ts` | `src/app/shared/index.ts` | Re-exporting multiple items from a directory | ### DFD Module Structure (Domain-Driven Design) The DFD (Data Flow Diagram) module uses a layered DDD architecture: ``` src/app/pages/dfd/ ├── application/ # Application services (orchestration, coordinators) │ ├── executors/ # Operation executors │ ├── services/ # app-*.service.ts files │ └── validators/ # Operation validators ├── domain/ # Domain models and events │ ├── entities/ # Domain entities │ ├── events/ # Domain events │ └── value-objects/ # Value objects ├── infrastructure/ # External library adapters │ ├── adapters/ # infra-*.adapter.ts files │ ├── constants/ # Infrastructure configuration │ ├── interfaces/ # Adapter interfaces │ └── services/ # infra-*.service.ts files ├── presentation/ # UI components and services │ ├── components/ # UI components │ └── services/ # ui-*.service.ts files ├── constants/ # Shared constants ├── interfaces/ # Shared interfaces ├── state/ # State management ├── types/ # Type definitions └── utils/ # Utility functions ``` ### Naming Rules 1. **Use kebab-case** for file names - Correct: `threat-model.service.ts` - Incorrect: `ThreatModelService.ts` or `threat_model_service.ts` 2. **Be descriptive** in naming - Correct: `threat-model-authorization.service.ts` - Incorrect: `tm-auth.service.ts` 3. **Group related files** by feature - Keep related components, services, and models together - Use barrel exports (index.ts) for clean imports 4. **Match class names** to file names - File: `threat-model.service.ts` - Class: `ThreatModelService` 5. **Use layer prefixes** in DFD module - Application layer: `app-*.service.ts` - Infrastructure layer: `infra-*.service.ts`, `infra-*.adapter.ts` - Presentation layer: `ui-*.service.ts` ### Migration Notes When renaming files: 1. Update all imports in the codebase 2. Update any barrel exports (index.ts files) 3. Check for impacts on tests 4. Run build and tests to verify ## 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 TMI provider for development: `?idp=tmi` 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`