feat: guidelines

.github/actions/docker/backend/action.yml

@@ -34,7 +34,7 @@ runs:
         gradle-encription-key: ${{ inputs.gradle-encryption-key }}
 
     - name: Cache Gradle Dependencies
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: |
           ~/.gradle/caches
@@ -51,7 +51,7 @@ runs:
       shell: bash
 
     - name: 🪄 Scan Docker images for vulnerabilities
-      uses: aquasecurity/trivy-action@0.20.0
+      uses: aquasecurity/trivy-action@0.24.0
       with:
         image-ref: ghcr.io/dallay/lyra:latest
         format: sarif
@@ -61,7 +61,7 @@ runs:
         cache-dir: /tmp/trivy-cache-lyra
 
     - name: ⇪ Upload Trivy Scan Report
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: trivy-lyra-report
         path: trivy-lyra-report.sarif

.github/actions/docker/frontend/action.yml

@@ -85,7 +85,7 @@ runs:
         password: ${{ inputs.ci_github_token }}
 
     - name: Cache Docker Layers
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: /tmp/.buildx-cache
         key: ${{ runner.os }}-buildx-${{ inputs.target }}-${{ steps.calculate-outputs.outputs.prod_tag }}
@@ -107,7 +107,7 @@ runs:
         cache-to: type=local,dest=/tmp/.buildx-cache,mode=max
 
     - name: 🪄 Scan Docker Images for Vulnerabilities
-      uses: aquasecurity/trivy-action@0.20.0
+      uses: aquasecurity/trivy-action@0.24.0
       with:
         image-ref: ${{ steps.calculate-outputs.outputs.repo_name }}:${{ steps.calculate-outputs.outputs.prod_tag }}
         format: sarif
@@ -117,7 +117,7 @@ runs:
         cache-dir: /tmp/trivy-cache-${{ inputs.target }}
 
     - name: ⇪ Upload Trivy Scan Report
-      uses: actions/upload-artifact@v3
+      uses: actions/upload-artifact@v4
       with:
         name: trivy-${{ inputs.target }}-report-${{ steps.calculate-outputs.outputs.prod_tag }}
         path: trivy-${{ inputs.target }}-report-${{ steps.calculate-outputs.outputs.prod_tag }}.sarif

.junie/guidelines.md

@@ -0,0 +1,250 @@
+# Lyra Project Development Guidelines
+
+This document provides essential information for developers working on the Lyra project.
+
+## Build and Configuration Instructions
+
+### Prerequisites
+
+- Java (version specified in `.java-version`)
+- Node.js (version specified in `.nvmrc`)
+- PNPM (for frontend package management)
+- Docker and Docker Compose (for running dependencies)
+- GNU Make (for using the provided Makefile targets)
+
+### Building the Project
+
+#### Backend (Kotlin/Spring Boot)
+
+The project uses Gradle as the build tool. The Gradle wrapper (`gradlew`) is included in the repository, so you don't need to install Gradle separately.
+
+```bash
+# Build the entire project
+./gradlew build
+
+# Clean and build
+./gradlew clean build
+
+# Build specific module
+./gradlew :apps:backend:build
+```
+
+You can also use the Makefile for common operations:
+
+```bash
+# Build the project
+make build
+
+# Clean the project
+make clean
+
+# Run tests
+make test
+```
+
+#### Frontend (Node.js)
+
+The frontend uses PNPM for package management:
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build frontend
+pnpm run build
+```
+
+### Running the Application
+
+#### Using Docker Compose
+
+The project includes Docker Compose configuration for running the application and its dependencies:
+
+```bash
+# Start all services
+docker compose up
+
+# Start specific services
+docker compose up postgresql keycloak
+
+# Run in detached mode
+docker compose up -d
+
+# Stop services
+docker compose down
+```
+
+#### Environment Configuration
+
+The project uses `.env` files for environment configuration. Copy `.env.example` to `.env` and adjust the values as needed:
+
+```bash
+cp .env.example .env
+```
+
+Key environment variables include:
+
+- `DATABASE_URL`: PostgreSQL connection string
+- `KEYCLOAK_URL`: Keycloak server URL
+- `API_KEY`: For external service authentication
+- See `.env.example` for a complete list of required variables
+
+## Testing Information
+
+### Backend Testing
+
+The backend uses JUnit 5 for testing, with custom annotations for different test types:
+
+- `@UnitTest`: For unit tests
+- `@IntegrationTest`: For integration tests
+
+Tests follow a BDD style with Given/When/Then comments and are organized by domain and layer (application, infrastructure, domain).
+
+#### Running Backend Tests
+
+```bash
+# Run all tests
+./gradlew test
+
+# Run only unit tests (filter by annotation)
+./gradlew test --includes-category "com.lyra.app.test.UnitTest"
+
+# Run integration tests (requires PostgreSQL & Keycloak)
+docker compose up -d postgresql keycloak
+./gradlew test --includes-category "com.lyra.app.test.IntegrationTest"
+### Running Backend Tests By Type
+
+```bash
+# Run all tests
+./gradlew test
+
+# Run only unit tests (filter by test class name)
+./gradlew test --tests "*UnitTest"
+
+# Alternative: Run unit tests using JUnit tags
+./gradlew test -DincludeTags=unit
+
+# Run integration tests (requires PostgreSQL & Keycloak)
+docker compose up -d postgresql keycloak
+./gradlew test --tests "*IntegrationTest"
+
+# Alternative: Run integration tests using JUnit tags
+./gradlew test -DincludeTags=integration
+# Run specific test
+./gradlew test --tests "com.lyra.app.healthcheck.HealthcheckUtilTest"
+```
+
+#### Writing Backend Tests
+
+1. Create a test class in the appropriate package under `src/test/kotlin`
+2. Annotate the class with `@UnitTest` or `@IntegrationTest`
+3. Write test methods with descriptive names using backticks
+4. Follow the Given/When/Then pattern
+
+Example:
+
+```kotlin
+@UnitTest
+class HealthcheckUtilTest {
+
+    @Test
+    fun `should return true when system is healthy`() {
+        // Given
+        val healthcheckUtil = HealthcheckUtil()
+
+        // When
+        val result = healthcheckUtil.isHealthy()
+
+        // Then
+        Assertions.assertTrue(result)
+    }
+}
+```
+
+### Frontend Testing
+
+Frontend tests are written using the Vitest JavaScript testing framework and are located in the `apps/frontend` directory.
+
+#### Running Frontend Tests
+
+```bash
+# Run all frontend tests
+pnpm test
+
+# Run tests with watch mode
+pnpm test:watch
+```
+
+#### Writing Frontend Tests
+
+Frontend tests follow a similar BDD style with describe/it blocks:
+
+```typescript
+describe('StringValueObject', () => {
+  it('should create a StringValueObject with a valid value', () => {
+    const valueObject = TestValueObject.create('test');
+    expect(valueObject.value).toBe('test');
+  });
+});
+```
+
+## Code Style and Development Practices
+
+### Code Style
+
+The project uses EditorConfig for consistent code style across different editors. The main settings are:
+
+- UTF-8 encoding
+- LF line endings
+- 2-space indentation for most files
+- 4-space indentation for Kotlin, Java, and some other file types
+
+### Architecture
+
+The project follows a clean architecture pattern with:
+
+- Domain layer: Core business logic and entities
+- Application layer: Use cases and application services
+- Infrastructure layer: External interfaces and implementations
+
+### Backend Development
+
+- The backend is built with Kotlin and Spring Boot
+- Uses reactive programming with Spring WebFlux
+- Follows CQRS pattern with command and query handlers
+- Uses event-driven architecture with event publishers
+
+### Frontend Development
+
+- The frontend consists of multiple applications:
+  - Lyra App (Nuxt.js)
+  - Lyra Landing Page (Astro)
+- Uses TypeScript for type safety
+- Follows domain-driven design principles
+
+### Database
+
+- PostgreSQL is used as the primary database
+- Keycloak is used for authentication and authorization
+
+### Containerization
+
+- Docker is used for containerization
+- Docker Compose is used for local development
+- Multiple Dockerfiles for different environments (development, production)
+
+## Debugging and Troubleshooting
+
+### Logs
+
+- Backend logs are available in the console and can be configured in `application.yml`
+- Docker logs can be viewed with `docker compose logs`
+
+### Common Issues
+
+- If you encounter database connection issues, ensure PostgreSQL is running and accessible
+- For Keycloak issues, check the Keycloak logs and ensure it's properly configured
+
+## Continuous Integration
+
+The project uses GitHub Actions for CI/CD, with workflows defined in the `.github` directory.

README.md

@@ -1,5 +1,5 @@
 <div align="center">
-<img src="apps/frontend/apps/lyra-landing-page/public/favicon.svg" height="50px"/> 
+<img src="apps/frontend/apps/lyra-landing-page/public/favicon.svg" height="50px"/>
 <h1>
  Lyra
 </h1>
@@ -55,6 +55,14 @@
 - [**Tailwindcss**](https://tailwindcss.com/) - A utility-first CSS framework for rapidly building custom designs.
 - [**tailwindcss-animated**](https://github.com/new-data-services/tailwindcss-animated) - Extended animation utilities for Tailwind CSS.
 - [**fontsource**](https://fontsource.org/) - Self-host Open Source fonts in neatly bundled NPM packages.
+- [**Spring Boot**](https://spring.io/projects/spring-boot) - The web framework for the backend.
+- [**Kotlin**](https://kotlinlang.org/) - A modern programming language that makes developers happier.
+- [**Gradle**](https://gradle.org/) - A powerful build tool for Java and other languages.
+- [**PostgreSQL**](https://www.postgresql.org/) - The world's most advanced open source relational database.
+- [**Keycloak**](https://www.keycloak.org/) - Open Source Identity and Access Management for modern applications and services.
+- [**Docker**](https://www.docker.com/) - A platform for developing, shipping, and running applications in containers.
+- [**Docker Compose**](https://docs.docker.com/compose/) - A tool for defining and running multi-container Docker applications.
+
 
 # Astro Starter Kit: Basics
 
@@ -116,4 +124,4 @@ Feel free to check [our documentation](https://docs.astro.build) or jump into ou
 
 ![Alt](https://repobeats.axiom.co/api/embed/fcbf097295ea4254db6b733582ac982db8fa4fe6.svg "Repobeats analytics image")
 
-![Alt](https://repobeats.axiom.co/api/embed/fcbf097295ea4254db6b733582ac982db8fa4fe6.svg "Repobeats analytics image")
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dallay/lyra)

apps/backend/src/test/kotlin/com/lyra/app/linkpreview/infrastructure/http/LinkPreviewControllerIntegrationTest.kt

@@ -30,7 +30,7 @@ internal class LinkPreviewControllerIntegrationTest : ControllerIntegrationTest(
                             "Typescript, Node.js, Java/Kotlin and Spring Boot.",
                         result?.description,
                     )
-                    assertEquals("/uploads/me.webp", result?.imageUrl)
+                    assertEquals("/images/me.webp", result?.imageUrl)
                     assertEquals("https://yunielacosta.com/", result?.url)
                 }
         }