improve: documentation

Author: lennyStreavent

README.md

@@ -1,4 +1,20 @@
-# AI Event Concepter
+# AI Event Concepter
+
+## 🚀 Quick Start (≤3 Commands)
+
+```bash
+git clone https://github.com/AET-DevOps25/team-git-push-force.git && cd team-git-push-force
+./start-dev.sh
+```
+
+**Access the application:**
+- Client (Angular frontend) at [http://localhost:4200](http://localhost:4200)
+- API Gateway at [http://localhost:8080](http://localhost:8080)  
+- Full stack running with real backend services
+
+---
+
+## Purpose
 
 ### What is the main functionality?
 
@@ -98,214 +114,103 @@ This project follows an API-first development approach. All API changes start wi
 
 ```
 /api                    # API specifications (single source of truth)
-  ├── gateway.yaml      # API Gateway specification
+  ├── gateway.yaml      # API Gateway specification  
   ├── user-service.yaml # User Service specification
   ├── concept-service.yaml # Concept Service specification
   ├── genai-service.yaml # GenAI Service specification
   ├── scripts/          # Code generation scripts
   └── README.md         # API documentation
 ```
 
-### Development Workflow
-
-1. **Update API Specifications**: Make changes to the OpenAPI specs in the `/api` directory
-2. **Lint OpenAPI Specs**: Run `npm run lint:openapi` to validate the specs
-3. **Generate Code**: Run `npm run generate:code` to generate code from the specs
-4. **Implement Business Logic**: Implement the business logic using the generated code
-5. **Run Tests**: Run tests to verify the implementation
-6. **Submit PR**: Submit a PR with the changes
+### Interactive API Documentation
 
-### Available Scripts
+- **Local Development**: Run `./start-docs.sh` to launch Swagger UI for all services
+- **Documentation Hub**: `docs/index.html` provides unified access to all API docs
+- **Individual Specs**: Each service OpenAPI spec can be viewed independently
 
-- `npm run lint:openapi`: Lint OpenAPI specifications
-- `npm run docs:openapi`: Generate API documentation
-- `npm run generate:code`: Generate code from OpenAPI specifications
+### API-First Engineering Process  
+1. **Design**: Update OpenAPI specifications first
+2. **Validate**: Automated linting and specification validation  
+3. **Generate**: Code generation from specifications
+4. **Test**: API contract testing and validation
+5. **Deploy**: Automated CI/CD pipeline deployment
 
-### Pre-commit Hooks
-
-This project uses pre-commit hooks to ensure code quality. The hooks are configured in `.pre-commit-config.yaml`.
-
-To install pre-commit hooks:
-
-```bash
-pip install pre-commit
-pre-commit install
-```
+**Engineering Process Evidence:**
+- ✅ **Documented Requirements**: Clear API contracts in `/api` directory
+- ✅ **Architecture Models**: UML diagrams (Analysis Object Model, Use Case, Component)
+- ✅ **API-First Workflow**: Specifications drive implementation
+- ✅ **Automated Validation**: Pre-commit hooks and CI pipeline checks
 
 ---
 
-## ⚙️ Prerequisites
-
-Make sure the following tools are installed:
-
-- [Node.js](https://nodejs.org/) (v22 or later)
-- Java JDK 21+
-- [Gradle](https://gradle.org/)
-- Docker and Docker Compose
-- Git
-
----
-
-## 🚀 Setup Instructions
-
-### Clone the Repository
-
-```bash
-git clone https://github.com/AET-DevOps25/team-git-push-force.git
-cd team-git-push-force
-```
-
-### Client Setup
-
-1. Navigate to the `client` directory:
-   ```bash
-   cd client
-   ```
-2. Install dependencies:
-   ```bash
-   npm install
-   ```
-
-### Backend Services Setup
-
-1. Generate code from OpenAPI specifications:
-   ```bash
-   ./api/scripts/gen-all.sh
-   ```
-
-2. Navigate to each service directory and build the project:
-   ```bash
-   # For Gateway
-   cd gateway
-   ./gradlew build
-
-   # For User Service
-   cd ../user-svc
-   ./gradlew build
-
-   # For Concept Service
-   cd ../concept-svc
-   ./gradlew build
-
-   # For GenAI Service
-   cd ../genai-svc
-   pip install -r requirements.txt
-   ```
-
-## Running the Application
-
-### Option 1: Using Docker Compose (Recommended)
-
-Before running the application, you need to generate code from the OpenAPI specifications. You can use the provided start-dev script which handles this automatically:
-
-```bash
-./start-dev.sh
-```
-
-This script will:
-1. Run code generation from OpenAPI specs
-2. Start all services using Docker Compose
-
-Alternatively, you can run these steps manually:
 
-```bash
-# First, generate code from OpenAPI specs
-./api/scripts/gen-all.sh
 
-# Then start Docker Compose
-docker-compose up
-```
+## 🧪 Testing & CI/CD Automation
 
-This will start all services:
-- Client (Angular frontend) at [http://localhost:3000](http://localhost:3000)
-- API Gateway at [http://localhost:8080](http://localhost:8080)
-- User Service at [http://localhost:8081](http://localhost:8081)
-- Concept Service at [http://localhost:8082](http://localhost:8082)
-- GenAI Service at [http://localhost:8083](http://localhost:8083)
-- Weaviate Vector Database at [http://localhost:8087](http://localhost:8087)
-- MinIO Object Storage at [http://localhost:9000](http://localhost:9000) (API) and [http://localhost:9001](http://localhost:9001) (Console)
+### Test Coverage & Automation
+- **Unit Tests**: JUnit (Java), pytest (Python), Jasmine (Angular)
+- **Integration Tests**: Database operations, API endpoints, service interactions  
+- **CI Pipeline**: GitHub Actions runs tests automatically on PR and merge
+- **Coverage Tools**: JaCoCo (Java), pytest-cov (Python), ng test (Angular)
 
-### 🚀 Development Environment (Default)
+### Automated Testing in CI
+- **On Pull Request**: Lint, unit tests, API validation
+- **On Merge**: Full test suite, integration tests, deployment
+- **API-First Validation**: OpenAPI spec validation and code generation verification
 
-The default docker-compose setup is optimized for development:
+See [Testing Strategy](./TESTING.md) for detailed coverage and methodology.
 
-```bash
-# Start development environment (default configuration)
-./start-dev.sh
-# OR manually:
-docker-compose up --build
-```
+## ⚙️ Prerequisites
 
-This setup:
-- ✅ **Development Mode**: Uses development environment configuration by default
-- ✅ **Real Backend**: All backend services running for full-stack development  
-- ✅ **Easy Setup**: Single command to start the entire stack
-- ✅ **Environment Flexibility**: Can easily switch to staging or production builds
+- [Node.js](https://nodejs.org/) (v22+), Java JDK 21+, Docker, Git
+- **All dependencies auto-installed** by setup scripts
 
-**Services Available:**
-- Client (Angular frontend) at [http://localhost:3000](http://localhost:3000)
-- All backend services running and connected
+## 🔧 Development Options
 
-**Environment Options:**
+### Environment Flexibility
 ```bash
 # Development (default)
-docker-compose up --build
+./start-dev.sh
 
-# Staging environment
+# Staging environment  
 CLIENT_BUILD_ENV=staging docker-compose up --build
 
-# Production environment  
+# Production environment
 CLIENT_BUILD_ENV=production docker-compose up --build
 ```
 
+### Manual Service Development
+For individual service development, see respective service READMEs:
+- [Gateway Service](./gateway/README.md) - `./gradlew bootRun --args='--spring.profiles.active=local'`
+- [User Service](./user-svc/README.md) - `./gradlew bootRun` 
+- [Concept Service](./concept-svc/README.md) - `./gradlew bootRun`
+- [GenAI Service](./genai-svc/README.md) - `python app.py`
+- [Client App](./client/README.md) - `ng serve`
 
-### Manual Development Setup
-
-Before starting the services manually, you need to generate code from the OpenAPI specifications:
-
-```bash
-./api/scripts/gen-all.sh
-```
-
-This will generate the necessary code for all services based on the OpenAPI specifications in the `/api` directory.
-
-#### Start the Client
-
-```bash
-cd client
-npm run dev
-```
-The client will be available at [http://localhost:3000](http://localhost:3000).
-
-#### Start the Gateway
-
-```bash
-cd gateway
-./gradlew bootRun
-```
-The API Gateway will be available at [http://localhost:8080](http://localhost:8080).
-
-#### Start the User Service
-
-```bash
-cd user-svc
-./gradlew bootRun
-```
-The User Service will be available at [http://localhost:8081](http://localhost:8081).
-
-#### Start the Concept Service
-
-```bash
-cd concept-svc
-./gradlew bootRun
-```
-The Concept Service will be available at [http://localhost:8082](http://localhost:8082).
-
-#### Start the GenAI Service
+---
 
-```bash
-cd genai-svc
-pip install -r requirements.txt
-python app.py
-```
-The GenAI Service will be available at [http://localhost:8083](http://localhost:8083).
+## 📚 Documentation
+
+### Core Documentation
+- **[API Specifications](./api/README.md)** - OpenAPI specs and API-first development
+- **[API Documentation Hub](./docs/index.html)** - Interactive Swagger UI for all services
+- **[Infrastructure & Deployment](./infrastructure/README.md)** - Terraform, Ansible, CI/CD setup
+- **[Monitoring](./helm/monitor/README.md)** - Prometheus, Grafana, alerting
+
+### Service Documentation
+- **[Concept Service](./concept-svc/README.md)** - Event concepts, PDF generation
+- **[User Service](./user-svc/README.md)** - User management, authentication, JWT tokens
+- **[GenAI Service](./genai-svc/README.md)** - LangChain integration, AI-powered features
+- **[Gateway Service](./gateway/README.md)** - API routing, JWT authentication
+- **[Client App](./client/README.md)** - Angular frontend, environment configuration
+
+### Development & Testing
+- **[Testing Strategy](./TESTING.md)** - Test coverage, CI automation, GenAI testing
+- **[GenAI Testing](./genai-svc/tests/README.md)** - Conversation history and concept suggestion tests
+- **[Helm Deployment](./helm/ai-event-concepter/README.md)** - Kubernetes deployment guide
+
+### Team Responsibilities
+Based on [CODEOWNERS](./.github/CODEOWNERS):
+- **@lenni108**: API specs (shared), Angular client, concept service, infrastructure, documentation
+- **@sfdamm**: Gateway, GenAI service, CI/CD workflows, Helm charts, API specs (shared), documentation
+- **@ClaudiaDuenzinger**: User service, monitoring stack, documentation

TESTING.md

@@ -0,0 +1,80 @@
+# Testing Strategy & Coverage
+
+## 🧪 Test Coverage Overview
+
+- **Unit Tests**: Comprehensive coverage via JUnit (Java) & pytest (Python)
+- **Integration Tests**: API endpoints, database operations, service interactions
+- **E2E Tests**: Critical user flows via Cypress (frontend)
+- **GenAI Tests**: LLM response parsing, conversation handling, document processing
+
+## 🚀 Running Tests
+
+### Individual Services
+```bash
+# Backend services (Spring Boot)
+cd concept-svc && ./gradlew test
+cd user-svc && ./gradlew test  
+cd gateway && ./gradlew test
+
+# GenAI service (Python)
+cd genai-svc && python -m pytest
+
+# Frontend (Angular)
+cd client && npm test
+```
+
+## 🔄 CI/CD Automation
+
+### GitHub Actions Pipeline
+- **On PR**: Unit tests, linting
+- **On merge**: Full test suite + deployment
+
+### Test Stages
+1. **Lint & Build**: Code quality checks
+2. **Unit Tests**: Fast isolated tests
+3. **Integration**: Database + API tests  
+
+## 🤖 GenAI Testing Strategy
+
+### LLM Response Testing
+- **Mock responses** for consistent unit tests
+- **Response parsing** validation (JSON extraction)
+- **Conversation history** handling
+- **Concept suggestion** accuracy
+
+### RAG Pipeline Testing
+- **Document ingestion** workflow
+- **Vector embedding** verification
+- **Similarity search** accuracy
+- **Context retrieval** relevance
+
+### Test Files
+- `genai-svc/tests/test_conversation_history.py`
+- `genai-svc/tests/test_concept_suggestions.py`
+- `genai-svc/tests/test_app.py`
+- `genai-svc/tests/test_health.py`
+
+## 🛠️ Test Configuration
+
+### Database Testing
+- **H2 in-memory** for unit tests
+- **PostgreSQL containers** for integration
+- **Test data isolation** per test class
+
+### Security Testing
+- **JWT validation** edge cases
+- **Authentication flows** validation
+- **Authorization** boundary testing
+
+## 🐛 Debugging Tests
+
+```bash
+# Verbose test output
+./gradlew test --info
+
+# Debug specific test
+./gradlew test --tests "ConceptServiceTest.createConcept"
+
+# Python debug mode
+python -m pytest -v -s tests/
+```