Initial Phoenix Sankofa Cloud setup

- Complete project structure with Next.js frontend
- GraphQL API backend with Apollo Server
- Portal application with NextAuth
- Crossplane Proxmox provider
- GitOps configurations
- CI/CD pipelines
- Testing infrastructure (Vitest, Jest, Go tests)
- Error handling and monitoring
- Security hardening
- UI component library
- Documentation

docs/TROUBLESHOOTING.md

@@ -0,0 +1,173 @@
+# Troubleshooting Guide
+
+Common issues and their solutions.
+
+## Installation Issues
+
+### Node Version Mismatch
+
+**Problem**: `Error: The engine "node" is incompatible with this module`
+
+**Solution**: Use Node.js 18+:
+```bash
+nvm install 20
+nvm use 20
+```
+
+### pnpm Not Found
+
+**Problem**: `command not found: pnpm`
+
+**Solution**: Install pnpm:
+```bash
+npm install -g pnpm
+```
+
+## Development Issues
+
+### Port Already in Use
+
+**Problem**: `Error: Port 3000 is already in use`
+
+**Solution**: 
+- Kill the process using the port: `lsof -ti:3000 | xargs kill`
+- Or use a different port: `PORT=3001 pnpm dev`
+
+### Database Connection Errors
+
+**Problem**: `Error: connect ECONNREFUSED`
+
+**Solution**:
+- Ensure PostgreSQL is running: `pg_isready`
+- Check connection string in `.env.local`
+- Verify database exists: `psql -l`
+
+### Module Not Found Errors
+
+**Problem**: `Module not found: Can't resolve '@/components/...'`
+
+**Solution**:
+- Clear `.next` directory: `rm -rf .next`
+- Reinstall dependencies: `pnpm install`
+- Restart dev server
+
+## Build Issues
+
+### TypeScript Errors
+
+**Problem**: Type errors during build
+
+**Solution**:
+- Run type check: `pnpm type-check`
+- Fix type errors
+- Ensure all dependencies are installed
+
+### Build Fails with Memory Error
+
+**Problem**: `JavaScript heap out of memory`
+
+**Solution**:
+```bash
+NODE_OPTIONS="--max-old-space-size=4096" pnpm build
+```
+
+## Test Issues
+
+### Tests Fail with "Cannot find module"
+
+**Problem**: Tests can't find modules
+
+**Solution**:
+- Clear test cache: `pnpm test --clearCache`
+- Reinstall dependencies
+- Check `vitest.config.ts` paths
+
+### Coverage Not Generated
+
+**Problem**: Coverage report is empty
+
+**Solution**:
+- Ensure coverage provider is installed
+- Run: `pnpm test:coverage`
+- Check `vitest.config.ts` coverage settings
+
+## API Issues
+
+### GraphQL Schema Errors
+
+**Problem**: Schema validation errors
+
+**Solution**:
+- Check `api/src/schema/typeDefs.ts`
+- Ensure all types are defined
+- Verify resolver return types match schema
+
+### Authentication Errors
+
+**Problem**: `UNAUTHENTICATED` errors
+
+**Solution**:
+- Check JWT token in request headers
+- Verify token hasn't expired
+- Ensure `JWT_SECRET` is set in `.env.local`
+
+## Portal Issues
+
+### Keycloak Connection Errors
+
+**Problem**: Cannot connect to Keycloak
+
+**Solution**:
+- Verify Keycloak URL in `.env.local`
+- Check network connectivity
+- Ensure Keycloak is running
+
+### Crossplane API Errors
+
+**Problem**: Cannot reach Crossplane API
+
+**Solution**:
+- Verify `NEXT_PUBLIC_CROSSPLANE_API` is set
+- Check if running in Kubernetes context
+- Verify API endpoint is accessible
+
+## GitOps Issues
+
+### ArgoCD Sync Failures
+
+**Problem**: ArgoCD applications fail to sync
+
+**Solution**:
+- Check ArgoCD logs: `kubectl logs -n argocd deployment/argocd-application-controller`
+- Verify Git repository access
+- Check application manifests
+
+## Performance Issues
+
+### Slow Build Times
+
+**Solution**:
+- Use pnpm instead of npm
+- Enable build cache
+- Reduce bundle size
+
+### Slow Development Server
+
+**Solution**:
+- Clear `.next` directory
+- Restart dev server
+- Check for large files in `public/`
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. Check existing GitHub issues
+2. Search documentation
+3. Ask in discussions
+4. Open a new issue with:
+   - Error message
+   - Steps to reproduce
+   - Environment details
+   - Relevant logs
+