From 6b4555a688f2331cd31a6284f7195cec615edf30 Mon Sep 17 00:00:00 2001 From: Jan Klattenhoff Date: Wed, 19 Mar 2025 12:02:22 +0100 Subject: [PATCH] docs: update documentation with setup and usage details --- Backend.md | 19 +++++ Coding-Standards.md | 4 + Development-Environment-Setup.md | 3 +- Frontend.md | 25 +++++- Home.md | 4 +- Running-the-Application.md | 142 +++++++++++++++++++++++++++++++ 6 files changed, 194 insertions(+), 3 deletions(-) create mode 100644 Running-the-Application.md diff --git a/Backend.md b/Backend.md index f9a42bb..be8b105 100644 --- a/Backend.md +++ b/Backend.md @@ -161,6 +161,25 @@ The backend exposes the following main API endpoints: 2. The API will be available at: http://localhost:8080 3. Swagger documentation: http://localhost:8080/swagger +4. Run tests: + ```bash + ./gradlew test + ``` + +5. Run specific test class: + ```bash + ./gradlew test --tests "FullyQualifiedClassName" + ``` + +6. Build the project: + ```bash + ./gradlew build + ``` + or for a clean build: + ```bash + ./gradlew clean build + ``` + ## Code Style Guidelines - Use PascalCase for classes with descriptive suffixes (Controller, Service, Entity) diff --git a/Coding-Standards.md b/Coding-Standards.md index c0523c8..98ea5a0 100644 --- a/Coding-Standards.md +++ b/Coding-Standards.md @@ -37,6 +37,10 @@ Where `` is one of: - `test`: Adding or refactoring tests - `chore`: Updating build tasks, etc; no production code change +References: +- [Conventional Commits](https://www.conventionalcommits.org/) +- [Semantic Commit Messages](https://seesparkbox.com/foundry/semantic_commit_messages) + Examples: ``` feat: add user balance display diff --git a/Development-Environment-Setup.md b/Development-Environment-Setup.md index 2947f94..43000a7 100644 --- a/Development-Environment-Setup.md +++ b/Development-Environment-Setup.md @@ -21,6 +21,7 @@ Before you begin, make sure you have the following tools installed: 4. **Bun** (Alternative to npm for faster package management) - [Bun installation](https://bun.sh/docs/installation) - Verify installation with: `bun --version` + - Required for the frontend build and package management 5. **IDE/Code Editor** - Backend: [IntelliJ IDEA](https://www.jetbrains.com/idea/) (recommended) or [Eclipse](https://www.eclipse.org/downloads/) @@ -167,7 +168,7 @@ If you encounter PostgreSQL connection issues: ```bash cd docker docker-compose down - docker volume rm casino_postgres_data + docker volume rm local_lf8_starter_postgres_data docker-compose up -d ``` diff --git a/Frontend.md b/Frontend.md index 83d17b2..cda9616 100644 --- a/Frontend.md +++ b/Frontend.md @@ -80,6 +80,11 @@ The application follows a consistent design system: - Secondary Text: `#94a3b8` (light gray) - Tertiary Text: `#64748b` (darker gray) +#### Additional Accents +- Yellow: `#fbbf24` (warnings, highlights) +- Red: `#ef4444` (errors, destructive actions) +- Purple: `#8b5cf6` (special features, premium content) + ### Component Library The application uses a consistent set of UI components: @@ -134,4 +139,22 @@ The application uses a consistent set of UI components: 2. The application will be available at http://localhost:4200 -3. API calls are proxied to the backend service running on http://localhost:8080 \ No newline at end of file +3. API calls are proxied to the backend service running on http://localhost:8080 + +4. For formatting code: + ```bash + bun run format + ``` + or + ```bash + prettier --write "src/**/*.{ts,html,css,scss}" + ``` + +5. For linting: + ```bash + bun run lint + ``` + or + ```bash + ng lint + ``` \ No newline at end of file diff --git a/Home.md b/Home.md index 440df92..17732aa 100644 --- a/Home.md +++ b/Home.md @@ -23,6 +23,7 @@ The frontend is built with Angular 18, providing a responsive and modern user in - **TailwindCSS** for styling and consistent design patterns - **Keycloak Integration** for authentication - **Stripe Payment Integration** for virtual currency deposits +- **Modal Animation Service** for consistent UI transitions [Frontend Documentation](Frontend) @@ -49,7 +50,8 @@ To get started with development or deployment, follow these guides: - [Development Environment Setup](Development-Environment-Setup) - [Running the Application](Running-the-Application) -- [Architecture Overview](Architecture-Overview) +- [Frontend Documentation](Frontend) +- [Backend Documentation](Backend) ## 📝 Developer Guidelines diff --git a/Running-the-Application.md b/Running-the-Application.md new file mode 100644 index 0000000..152d592 --- /dev/null +++ b/Running-the-Application.md @@ -0,0 +1,142 @@ +# Running the Application + +This guide describes how to run the Casino Gaming Platform locally. + +## Prerequisites + +Ensure you have all requirements installed as described in the [Development Environment Setup](Development-Environment-Setup) guide. + +## Starting the Infrastructure + +Before running the application, you need to start the required infrastructure: + +1. **Start Docker services** + ```bash + cd docker + docker-compose up -d + ``` + + This starts: + - PostgreSQL database (port 5432) + - PostgreSQL for Keycloak (port 9433) + - Keycloak authentication server (port 9090) + +2. **Verify services are running** + ```bash + docker ps + ``` + +## Running the Backend + +1. **Navigate to the backend directory** + ```bash + cd backend + ``` + +2. **Start the Spring Boot application** + ```bash + ./gradlew bootRun + ``` + + Alternatively, you can run it from your IDE by running the `CasinoApplication` class. + +3. **Verify the backend is running** + - Open http://localhost:8080/swagger in your browser to see the Swagger UI + - Run a health check: http://localhost:8080/api/health + +## Running the Frontend + +1. **Navigate to the frontend directory** + ```bash + cd frontend + ``` + +2. **Install dependencies** (if not already done) + ```bash + bun install + ``` + +3. **Start the development server** + ```bash + bun run start + ``` + or + ```bash + bunx @angular/cli serve --proxy-config src/proxy.conf.json + ``` + +4. **Access the application** + - Open http://localhost:4200 in your browser + +## Using Docker Compose for Everything + +For convenience, you can run the entire stack using Docker Compose: + +1. **Build the containers** + ```bash + docker-compose -f docker/docker-compose.yml build + ``` + +2. **Start the services** + ```bash + docker-compose -f docker/docker-compose.yml up -d + ``` + +3. **Access the application** + - Frontend: http://localhost:4200 + - Backend: http://localhost:8080 + - Keycloak: http://localhost:9090 + +## Stopping the Application + +1. **Stop the frontend** + - Press `Ctrl+C` in the terminal where the frontend is running + +2. **Stop the backend** + - Press `Ctrl+C` in the terminal where the backend is running + +3. **Stop Docker services** + ```bash + cd docker + docker-compose down + ``` + +## Common Issues and Solutions + +### Frontend cannot connect to backend + +- Ensure the backend is running +- Check that the proxy configuration in `src/proxy.conf.json` is correct +- Verify that Docker services are running + +### Authentication issues + +- Ensure Keycloak is running and accessible at http://localhost:9090 +- Check that the user exists in the Keycloak realm +- Verify the client configuration in Keycloak + +### Database connection issues + +- Ensure PostgreSQL is running +- Check the database connection settings in `application.properties` +- Try resetting the database (see [Troubleshooting](Development-Environment-Setup#troubleshooting)) + +## Development Modes + +### Backend Development with Hot Reload + +Spring Boot Development Tools provide hot reload capabilities: + +```bash +./gradlew bootRun --args="--spring.devtools.restart.enabled=true" +``` + +### Frontend Development with HMR + +Angular CLI provides hot module replacement: + +```bash +bun run start +``` + +This automatically enables HMR for faster development. \ No newline at end of file