diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2998b41 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,81 @@ +# Contributing to Java AI - AI Shop + +This project welcomes contributions and suggestions. Most contributions require you to agree to a +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +## How to contribute + +### Reporting bugs + +If you find a bug, please report it by [opening an issue](https://github.com/Azure-Samples/java-ai/issues/new). Please include: + +- A clear and descriptive title +- A detailed description of the issue +- Steps to reproduce the problem +- Expected vs actual behavior +- Screenshots if applicable +- Environment details (OS, Java version, etc.) + +### Suggesting enhancements + +Enhancement suggestions are tracked as [GitHub issues](https://github.com/Azure-Samples/java-ai/issues). When creating an enhancement suggestion, please include: + +- A clear and descriptive title +- A detailed description of the proposed enhancement +- An explanation of why this enhancement would be useful +- If possible, a draft implementation approach + +### Pull requests + +1. Fork the repository +2. Create a feature branch from `main` +3. Make your changes +4. Add or update tests as needed +5. Ensure all tests pass +6. Update documentation if needed +7. Submit a pull request + +### Development setup + +To set up the development environment: + +1. Clone the repository +2. Ensure you have Java 17+ installed +3. Install Azure CLI and Azure Developer CLI (azd) +4. Install Docker or Podman +5. Follow the instructions in the [README.md](README.md) to build and run locally + +### Code style + +- Follow existing code style and formatting +- Use meaningful variable and method names +- Add comments for complex logic +- Ensure all public methods have appropriate documentation + +### Testing + +- Add unit tests for new functionality +- Ensure all existing tests pass +- Test your changes locally before submitting + +### Documentation + +- Update README.md if needed +- Add inline documentation for new public APIs +- Update any relevant markdown files in the documentation + +## Resources + +- [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) +- [Azure Developer CLI Documentation](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) +- [Spring Boot Documentation](https://spring.io/projects/spring-boot) +- [React Documentation](https://reactjs.org/docs/getting-started.html) \ No newline at end of file diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..7bbf315 --- /dev/null +++ b/ISSUE_TEMPLATE.md @@ -0,0 +1,63 @@ +--- +name: Issue template +about: Use this template to report bugs or request features +title: '' +labels: '' +assignees: '' + +--- + +## Issue Type + +- [ ] Bug report +- [ ] Feature request +- [ ] Documentation issue +- [ ] Question + +## Description + + +## Steps to Reproduce (for bugs) + +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +## Expected Behavior + + +## Actual Behavior + + +## Screenshots + + +## Environment + +- OS: [e.g. Windows 10, macOS, Ubuntu 20.04] +- Java Version: [e.g. Java 17] +- Azure CLI Version: [e.g. 2.x.x] +- Azure Developer CLI Version: [e.g. 1.x.x] +- Docker Version: [e.g. 20.x.x] + +## Additional Context + + +## Logs + +``` +Paste logs here +``` + +## Feature Request Details (if applicable) + + +### Use Case + + +### Proposed Solution + + +### Alternatives Considered + \ No newline at end of file diff --git a/README.md b/README.md index 9da6bd9..d794699 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,103 @@ The functional architecture of the application is as follows: ![Functional Architecture](./media/functional-architecture.png) +## Features + +This AI Shop application demonstrates several key features: + +- **Multi-modal AI Integration**: Uses Azure OpenAI's vision capabilities to analyze product images and generate comprehensive product information automatically +- **Microservices Architecture**: Built with Spring Boot microservices including API Gateway, Eureka service discovery, and specialized services for different functions +- **Cloud-Native Deployment**: Fully containerized application deployable to Azure Container Apps with Azure Developer CLI (azd) +- **AI-Powered Categorization**: Intelligent product categorization using LangChain4j for enhanced product organization +- **Secure Blob Storage**: Azure Blob Storage integration with SAS token generation for secure image handling +- **Modern React UI**: Clean, responsive user interface for easy product upload and management +- **Enterprise Security**: Entra ID authentication and role-based access control for production readiness + +## Getting Started + +### Quick Start with Azure + +The fastest way to get started is to deploy directly to Azure: + +1. **Fork this repository** to your GitHub account +2. **Open in GitHub Codespace** (recommended) or clone locally +3. **Login to Azure** and run deployment: + ```bash + azd auth login + azd up + ``` +4. **Access your application** at the provided endpoint after deployment completes + +### Local Development + +For local development and testing: + +1. **Prerequisites**: Ensure you have Java 17+, Azure CLI, azd, and Docker installed +2. **Build the common module**: Follow instructions in [src/java-ai-common/common/README.md](src/java-ai-common/common/README.md) +3. **Start services in order**: Follow the detailed steps in the "Run locally" section below +4. **Access the application** at http://localhost:3000 + +## Guidance + +### Architecture Decisions + +This application follows several architectural patterns: + +- **Microservices Pattern**: Each service has a single responsibility and can be deployed independently +- **API Gateway Pattern**: Centralized entry point for all client requests with service orchestration +- **Service Discovery**: Uses Eureka for dynamic service registration and discovery in local development +- **Event-Driven Architecture**: Services communicate through well-defined APIs and events +- **Cloud-First Design**: Built specifically for Azure Container Apps with proper scaling and monitoring + +### Best Practices Implemented + +- **Security**: Entra ID authentication, managed identities, and secure secret management +- **Monitoring**: Azure Log Analytics integration for comprehensive observability +- **Scalability**: Container Apps auto-scaling based on demand +- **Reliability**: Health checks, graceful degradation, and proper error handling +- **Performance**: Optimized container images and efficient resource utilization + +### Customization Guidelines + +To adapt this application for your use case: + +1. **Model Configuration**: Update AI model deployments in `infra/bicep/deploy.bicep` +2. **Service Logic**: Modify business logic in individual service modules +3. **UI Customization**: Update React components in `src/ai-shop-ui` +4. **Data Models**: Extend DTOs in `src/java-ai-common` for additional fields +5. **Infrastructure**: Adjust Azure resources in bicep templates as needed + +## Resources + +### Documentation + +- [Azure Developer CLI Documentation](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) +- [Azure Container Apps Documentation](https://learn.microsoft.com/en-us/azure/container-apps/) +- [Azure OpenAI Service Documentation](https://learn.microsoft.com/en-us/azure/ai-services/openai/) +- [Spring Boot Documentation](https://spring.io/projects/spring-boot) +- [Spring AI Documentation](https://spring.io/projects/spring-ai) +- [LangChain4j Documentation](https://docs.langchain4j.dev/) + +### Learning Resources + +- [Azure AI Services Learning Path](https://learn.microsoft.com/en-us/training/paths/get-started-azure-ai/) +- [Java on Azure Learning Path](https://learn.microsoft.com/en-us/training/paths/java-on-azure/) +- [Microservices with Spring Boot](https://spring.io/microservices) +- [React.js Tutorial](https://reactjs.org/tutorial/tutorial.html) + +### Sample Code and Templates + +- [Azure-Samples GitHub Organization](https://github.com/Azure-Samples) +- [Azure Developer CLI Templates](https://azure.github.io/awesome-azd/) +- [Spring Boot Sample Applications](https://github.com/spring-projects/spring-boot/tree/main/spring-boot-samples) + +### Community and Support + +- [Azure Developer Community](https://techcommunity.microsoft.com/t5/azure-developer-community/ct-p/AzureDevCommunity) +- [Stack Overflow - Azure](https://stackoverflow.com/questions/tagged/azure) +- [GitHub Issues](https://github.com/Azure-Samples/java-ai/issues) for project-specific questions +- [Microsoft Q&A for Azure](https://learn.microsoft.com/en-us/answers/products/azure) + ## Prerequisites Easiest way to start is to Fork and [open the repository in a GitHub Codespace](https://github.com/codespaces/new/Azure-Samples/java-ai) as it contains all the prerequisites. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b8bfe2b --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,48 @@ +# Security Policy + +## Supported Versions + +We release patches for security vulnerabilities. Which versions are eligible for receiving such patches depends on the CVSS v3.0 Rating: + +| CVSS v3.0 | Supported Versions | +| --------- | ----------------------------------------- | +| 9.0-10.0 | Releases within the previous three months | +| 4.0-8.9 | Most recent release | + +## Reporting a Vulnerability + +Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/Microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). + +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://docs.microsoft.com/en-us/previous-versions/tn-archive/cc751383(v=technet.10)), please report it to us as described below. + +## Reporting Security Issues + +**Please do not report security vulnerabilities through public GitHub issues.** + +Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://msrc.microsoft.com/create-report). + +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://www.microsoft.com/en-us/msrc/pgp-key-msrc). + +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://www.microsoft.com/msrc). + +Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: + +* Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) +* Full paths of source file(s) related to the manifestation of the issue +* The location of the affected source code (tag/branch/commit or direct URL) +* Any special configuration required to reproduce the issue +* Step-by-step instructions to reproduce the issue +* Proof-of-concept or exploit code (if possible) +* Impact of the issue, including how an attacker might exploit the issue + +This information will help us triage your report more quickly. + +If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://microsoft.com/msrc/bounty) page for more details about our active programs. + +## Preferred Languages + +We prefer all communications to be in English. + +## Policy + +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://www.microsoft.com/en-us/msrc/cvd). \ No newline at end of file diff --git a/azure-dev.yml b/azure-dev.yml new file mode 100644 index 0000000..e7cdab4 --- /dev/null +++ b/azure-dev.yml @@ -0,0 +1,79 @@ +# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json + +name: java-ai-lab + +workflows: + up: + - azd: provision + - azd: package --all + - azd: deploy --all + +infra: + provider: bicep + path: infra/bicep + +services: + api-gateway: + resourceName: ${apiGatewayContainerAppName} + project: ./src/api-gateway + host: containerapp + language: java + docker: + registry: ${AZURE_CONTAINER_REGISTRY_ENDPOINT} + image: java-ai/api-gateway + tag: ${AZD_PROVISION_TIMESTAMP} + remoteBuild: true + + ai-image-processing-service: + resourceName: ${imageProcessingServiceContainerAppName} + project: ./src/ai-image-processing-service + host: containerapp + language: java + docker: + registry: ${AZURE_CONTAINER_REGISTRY_ENDPOINT} + image: java-ai/ai-image-processing-service + tag: ${AZD_PROVISION_TIMESTAMP} + remoteBuild: true + + blob-storage-service: + resourceName: ${blobStorageServiceContainerAppName} + project: ./src/blob-storage-service + host: containerapp + language: java + docker: + registry: ${AZURE_CONTAINER_REGISTRY_ENDPOINT} + image: java-ai/blob-storage-service + tag: ${AZD_PROVISION_TIMESTAMP} + remoteBuild: true + + ai-shop-ui: + resourceName: ${aiShopUiContainerApps} + project: ./src/ai-shop-ui + host: containerapp + language: js + docker: + registry: ${AZURE_CONTAINER_REGISTRY_ENDPOINT} + image: java-ai/ai-shop-ui + tag: ${AZD_PROVISION_TIMESTAMP} + remoteBuild: true + + item-category-service: + resourceName: ${itemCategoryServiceContainerAppName} + project: ./src/item-category-service + host: containerapp + language: java + docker: + registry: ${AZURE_CONTAINER_REGISTRY_ENDPOINT} + image: java-ai/item-category-service + tag: ${AZD_PROVISION_TIMESTAMP} + remoteBuild: true + +hooks: + postprovision: + posix: + shell: sh + run: 'chmod +x ./infra/bicep/hooks/export-env.sh; ./infra/bicep/hooks/export-env.sh' + prepackage: + posix: + shell: sh + run: 'chmod +x ./infra/bicep/hooks/build-java.sh; ./infra/bicep/hooks/build-java.sh' \ No newline at end of file diff --git a/infra/bicep/deploy.bicep b/infra/bicep/deploy.bicep index 53bceab..b1cecfb 100644 --- a/infra/bicep/deploy.bicep +++ b/infra/bicep/deploy.bicep @@ -23,8 +23,8 @@ param environmentName string = 'dev' /* ----------------------------- Infrastructure ----------------------------- */ -@description('The name of the storage account. Default to "st".') -param storageAccountName string = 'st${replace(workloadName, '-', '')}${environmentName}${take(uniqueString(resourceGroup().id), 5)}' +@description('The name of the storage account. Default to "st".') +param storageAccountName string = 'st${take(replace(workloadName, '-', ''), 6)}${environmentName}${take(uniqueString(resourceGroup().id), 5)}' @description('The name of the storage account blob container. Default to "aishopinbox".') param storageAccountBlobContainerName string = 'aishopinbox' @@ -284,6 +284,7 @@ resource azureOpenAI 'Microsoft.CognitiveServices/accounts@2024-04-01-preview' = properties: { customSubDomainName: azureOpenAISubDomainName publicNetworkAccess: 'Enabled' + disableLocalAuth: true } }