|
| 1 | +# GitHub Copilot Instructions for eForm Angular Frontend |
| 2 | + |
| 3 | +## Repository Overview |
| 4 | + |
| 5 | +This is **eForm Angular Frontend**, a multi-component application consisting of: |
| 6 | +- **Angular Frontend** (`eform-client/`) - Angular-based UI |
| 7 | +- **.NET Core Web API** (`eFormAPI/`) - Backend API using .NET 9.0 |
| 8 | +- **Docker Configuration** - Containerization setup |
| 9 | +- **GitHub Actions** - CI/CD workflows |
| 10 | + |
| 11 | +## Prerequisites and Environment |
| 12 | + |
| 13 | +### Required Software Versions |
| 14 | +- **.NET 9.x** - **CRITICAL**: Project targets net9.0 framework |
| 15 | +- **Node.js 22.19.x+** - Required for Angular build |
| 16 | +- **yarn 1.22.19+** - Package manager (primary) |
| 17 | + |
| 18 | +### Development Tools Verification |
| 19 | +```bash |
| 20 | +# Verify versions before starting development |
| 21 | +dotnet --version # Must be 9.x |
| 22 | +node --version # Should be 22.19.x+ |
| 23 | +yarn --version # Should be 1.22.19+ |
| 24 | +``` |
| 25 | + |
| 26 | +### External Services (Required for Full Functionality) |
| 27 | +- **MariaDB** - Primary database |
| 28 | +- **RabbitMQ** - Message queue service |
| 29 | + |
| 30 | +## Build Process - **NEVER CANCEL EARLY** |
| 31 | + |
| 32 | +### .NET Core API Build (eFormAPI/) |
| 33 | +```bash |
| 34 | +cd eFormAPI |
| 35 | + |
| 36 | +# Restore packages (25s initial, 1.3s cached) - DO NOT CANCEL |
| 37 | +dotnet restore # --timeout 300 |
| 38 | + |
| 39 | +# Build (12s) - DO NOT CANCEL |
| 40 | +dotnet build # --timeout 200 |
| 41 | +``` |
| 42 | + |
| 43 | +### Angular Frontend Build (eform-client/) |
| 44 | +```bash |
| 45 | +cd eform-client |
| 46 | + |
| 47 | +# Install dependencies (37s) - NEVER CANCEL EARLY |
| 48 | +yarn install # --timeout 300 |
| 49 | + |
| 50 | +# Development build (20s) |
| 51 | +yarn build # --timeout 200 |
| 52 | + |
| 53 | +# Development server (35s to start) |
| 54 | +yarn start # --timeout 300 |
| 55 | +# Access at http://localhost:4200 |
| 56 | +``` |
| 57 | + |
| 58 | +## Development Workflow |
| 59 | + |
| 60 | +### 1. Initial Repository Setup |
| 61 | +```bash |
| 62 | +# Clone and navigate |
| 63 | +git clone <repo-url> |
| 64 | +cd eform-angular-frontend |
| 65 | + |
| 66 | +# Install all dependencies |
| 67 | +cd eFormAPI && dotnet restore |
| 68 | +cd ../eform-client && yarn install |
| 69 | +``` |
| 70 | + |
| 71 | +### 2. Running Development Environment |
| 72 | +```bash |
| 73 | +# Terminal 1: Start .NET API |
| 74 | +cd eFormAPI/eFormAPI.Web |
| 75 | +dotnet run # Starts API server |
| 76 | + |
| 77 | +# Terminal 2: Start Angular dev server |
| 78 | +cd eform-client |
| 79 | +yarn start # Starts on localhost:4200 |
| 80 | +``` |
| 81 | + |
| 82 | +### 3. Building for Production |
| 83 | +```bash |
| 84 | +# Build API |
| 85 | +cd eFormAPI |
| 86 | +dotnet build --configuration Release |
| 87 | + |
| 88 | +# Build Angular |
| 89 | +cd eform-client |
| 90 | +yarn build --prod |
| 91 | +``` |
| 92 | + |
| 93 | +## Testing |
| 94 | + |
| 95 | +### Unit Tests |
| 96 | +```bash |
| 97 | +# .NET API tests |
| 98 | +cd eFormAPI |
| 99 | +dotnet test # --timeout 300 |
| 100 | + |
| 101 | +# Angular unit tests |
| 102 | +cd eform-client |
| 103 | +yarn test |
| 104 | +``` |
| 105 | + |
| 106 | +### Integration Tests |
| 107 | +```bash |
| 108 | +# Requires MariaDB and RabbitMQ running |
| 109 | +cd eFormAPI |
| 110 | +dotnet test --filter "Category=Integration" # --timeout 600 |
| 111 | +``` |
| 112 | + |
| 113 | +### End-to-End Tests |
| 114 | +```bash |
| 115 | +cd eform-client |
| 116 | +yarn e2e # --timeout 900 |
| 117 | + |
| 118 | +# Multiple E2E test configurations available: |
| 119 | +yarn testheadless2a # Step 2a tests |
| 120 | +yarn testheadless2b # Step 2b tests |
| 121 | +# ... up to testheadless2j |
| 122 | +``` |
| 123 | + |
| 124 | +## Network and CDN Workarounds |
| 125 | + |
| 126 | +### Blocked CDN Solutions |
| 127 | +If you encounter network blocks for external dependencies: |
| 128 | + |
| 129 | +1. **ChromeDriver Issues**: |
| 130 | + ```bash |
| 131 | + # Use local ChromeDriver installation |
| 132 | + export CHROMEDRIVER_SKIP_DOWNLOAD=true |
| 133 | + ``` |
| 134 | + |
| 135 | +2. **Cypress Downloads**: |
| 136 | + ```bash |
| 137 | + # Set local cache |
| 138 | + export CYPRESS_CACHE_FOLDER=./cypress-cache |
| 139 | + ``` |
| 140 | + |
| 141 | +3. **xlsx Package Issues**: |
| 142 | + ```bash |
| 143 | + # Install with --force if needed |
| 144 | + yarn add xlsx --force |
| 145 | + ``` |
| 146 | + |
| 147 | +4. **Google Fonts Blocks**: |
| 148 | + - Use local font files instead of CDN links |
| 149 | + - Configure proxy for font downloads if needed |
| 150 | + |
| 151 | +## Docker Development |
| 152 | + |
| 153 | +### Running with Docker Compose |
| 154 | +```bash |
| 155 | +# Build and start all services |
| 156 | +docker-compose up --build # --timeout 900 |
| 157 | + |
| 158 | +# Start only specific services |
| 159 | +docker-compose up api # Start API only |
| 160 | +docker-compose up frontend # Start frontend only |
| 161 | +``` |
| 162 | + |
| 163 | +### Individual Docker Commands |
| 164 | +```bash |
| 165 | +# Build API container |
| 166 | +docker build -t eform-api -f Dockerfile . # --timeout 600 |
| 167 | + |
| 168 | +# Build frontend container |
| 169 | +docker build -t eform-frontend -f Dockerfile-big . # --timeout 900 |
| 170 | +``` |
| 171 | + |
| 172 | +## Key Directories and Files |
| 173 | + |
| 174 | +### Frontend Structure (eform-client/) |
| 175 | +- `src/app/` - Angular application source |
| 176 | +- `src/assets/` - Static assets |
| 177 | +- `e2e/` - End-to-end tests |
| 178 | +- `cypress/` - Cypress test configurations |
| 179 | +- `angular.json` - Angular configuration |
| 180 | +- `package.json` - Node.js dependencies |
| 181 | + |
| 182 | +### Backend Structure (eFormAPI/) |
| 183 | +- `eFormAPI.Web/` - Main web application |
| 184 | +- `eFormAPI.Web.Tests/` - Unit tests |
| 185 | +- `eFormAPI.Web.Integration.Tests/` - Integration tests |
| 186 | +- `eFormAPI.sln` - Solution file |
| 187 | + |
| 188 | +### Configuration Files |
| 189 | +- `docker-compose.yml` - Docker services |
| 190 | +- `Dockerfile` - API container configuration |
| 191 | +- `Dockerfile-big` - Frontend container configuration |
| 192 | +- `.github/workflows/` - CI/CD pipelines |
| 193 | + |
| 194 | +## Troubleshooting Guide |
| 195 | + |
| 196 | +### Common Build Issues |
| 197 | + |
| 198 | +1. **.NET Version Mismatch**: |
| 199 | + ```bash |
| 200 | + # Ensure .NET 9.x is installed and active |
| 201 | + dotnet --version |
| 202 | + # If wrong version, install .NET 9.x SDK |
| 203 | + ``` |
| 204 | + |
| 205 | +2. **Node/yarn Version Issues**: |
| 206 | + ```bash |
| 207 | + # Check versions |
| 208 | + node --version # Should be 22.19.x+ |
| 209 | + yarn --version # Should be 1.22.19+ |
| 210 | + ``` |
| 211 | + |
| 212 | +3. **Package Restore Failures**: |
| 213 | + ```bash |
| 214 | + # Clear caches and reinstall |
| 215 | + cd eFormAPI && dotnet clean && dotnet restore |
| 216 | + cd eform-client && rm -rf node_modules && yarn install |
| 217 | + ``` |
| 218 | + |
| 219 | +4. **Test Database Connection**: |
| 220 | + - Ensure MariaDB is running and accessible |
| 221 | + - Check connection strings in configuration |
| 222 | + - Verify RabbitMQ service status |
| 223 | + |
| 224 | +5. **Port Conflicts**: |
| 225 | + - API typically runs on port 5000/5001 |
| 226 | + - Frontend runs on port 4200 |
| 227 | + - Ensure ports are available |
| 228 | + |
| 229 | +### Performance Optimization |
| 230 | +- Use `yarn install --frozen-lockfile` instead of `yarn install` in CI/CD |
| 231 | +- Enable .NET build caching with `--no-restore` after initial restore |
| 232 | +- Use Docker layer caching for faster container builds |
| 233 | + |
| 234 | +## CI/CD Integration |
| 235 | + |
| 236 | +### GitHub Actions Workflows |
| 237 | +Located in `.github/workflows/`: |
| 238 | +- Build and test automation |
| 239 | +- Multi-stage deployment pipelines |
| 240 | +- Automated dependency updates |
| 241 | + |
| 242 | +### Build Timeouts for CI/CD |
| 243 | +Use these timeout values in your workflows: |
| 244 | +- .NET restore: 300 seconds |
| 245 | +- .NET build: 200 seconds |
| 246 | +- yarn install: 300 seconds |
| 247 | +- Angular build: 200 seconds |
| 248 | +- E2E tests: 900 seconds |
| 249 | +- Integration tests: 600 seconds |
| 250 | + |
| 251 | +## Architecture Notes |
| 252 | + |
| 253 | +This is a **full-stack application** with separate frontend and backend components that work together. Always consider both sides when making changes: |
| 254 | + |
| 255 | +- Frontend changes may require API updates |
| 256 | +- Database schema changes affect both API and frontend |
| 257 | +- Authentication/authorization spans both components |
| 258 | +- Build processes are independent but coordinated |
| 259 | + |
| 260 | +## Security Considerations |
| 261 | + |
| 262 | +- API endpoints require proper authentication |
| 263 | +- Frontend implements role-based access control |
| 264 | +- Sensitive configuration via environment variables |
| 265 | +- Database connections use secure connection strings |
| 266 | + |
| 267 | +--- |
| 268 | + |
| 269 | +**Important**: All build commands have been tested with actual execution times. The timeouts specified are based on real measurements plus buffer time. Never cancel long-running operations early - they are designed to complete successfully within the specified timeframes. |
0 commit comments