Iced Latte

A production-grade Java coffee marketplace — built in the open, for engineers who want real experience.

🌐 Live Demo · 📖 API Docs · 🟢 Good First Issues · 💬 Community

---

📊 Key stats across all three repositories:

Repository	⭐ Stars	🍴 Forks
🔧 Backend
🎨 Frontend
🧪 QA

⭐ If this project helps you learn or inspires you, please give it a star — it means a lot to the community!

---

🚀 Quick Start

📋 Prerequisites: Java 25, Maven 3.9+, Docker Desktop

# 1. 📥 Clone
git clone https://github.com/Sunagatov/Iced-Latte.git && cd Iced-Latte

# 2. 🐳 Start infrastructure (PostgreSQL, Redis, MinIO)
docker compose up -d postgres redis minio minio-init

# 3. ▶️ Run (uses committed .env — local development values and placeholders)
# Linux / macOS / Git Bash on Windows:
export $(cat .env | xargs) && mvn spring-boot:run

🪟 Windows (PowerShell / CMD): the export command above won't work. Use the IntelliJ EnvFile plugin or the full Docker path instead — see START.md.

🌐 App runs at http://localhost:8083 · 📚 Swagger UI at http://localhost:8083/api/docs/swagger-ui/index.html

🔐 Test login: olivia@example.com / p@ss1logic11 (15 seed users, all share this password)

💡 Using IntelliJ? See START.md for IDE run configuration, Docker-only setup, and troubleshooting.

🎞️ Want to run the frontend too? Clone the frontend repo as a sibling and use Option C in START.md:

git clone https://github.com/Sunagatov/Iced-Latte-Frontend.git  # sibling of Iced-Latte/
docker compose --profile backend --profile frontend up -d --build

Frontend at http://localhost:3000 — built from source every time.

🧪 Run the tests:

mvn test

✅ Tests use Testcontainers — Docker must be running.

---

📸 Preview

Live application interface

---

🤔 What is this?

Iced Latte is a non-profit sandbox project started in 2022 as a private pet project, then opened to the community to give junior engineers, students, and mentees practical experience in a real tech project with processes similar to those in actual tech teams. The first participants were students, Telegram channel subscribers, and mentees from ADPList and Women In Tech. The project has since grown and earned recognition from both the open-source community and the wider tech community.

⭐ If this project helps you learn or inspires you, please give it a star — it means a lot to the community!

---

🏆 Recognition

Iced Latte has earned recognition from the broader tech community.

🔥 GitHub Trending 🔥 — May 22, 2024

• The backend repository reached GitHub's Trending page — listed among resources "the GitHub community is most excited about today" — gaining 85 stars in a single day with 27 active contributors. (link to the archive)

🥉 KaiCode 2024 Finalist 🥉

• Iced Latte made it to the finals of KaiCode — an annual open-source festival launched by Huawei, which positions itself as an incubator of open-source technologies and rewards the most promising projects. Iced Latte was selected among 412 applications and placed in the third group of 26 finalist repositories considered for the prize. Jury members are not allowed to assess their own projects, so the selection was fully independent.

🛠️JetBrains Open Source License 🛠

• Iced Latte was recognized by JetBrains — a leading software company specializing in intelligent development tools. As an active participant in the open-source community, JetBrains supports recognized global open-source projects by providing complimentary licenses for non-commercial development. JetBrains granted Iced Latte 8 free All Products Pack licenses (February 2024, License Reference No. D379769990).

👨💻 Recommended by Eddie Jaoude 👨

• Iced Latte was recommended by Eddie Jaoude — one of the most influential open-source experts, a GitHub Star with 174K followers on X and 17.6K on LinkedIn — who called it a great example of a Java open-source project. Many Iced Latte contributors shared their positive experience in the comments.

---

🛠️ Tech Stack

📂 Category	🔧 Technology
💻 Language	Java 25
🏗️ Framework	Spring Boot 4.0, Spring Security, Spring Data JPA, Spring Retry, Spring Actuator
🗄️ Database	PostgreSQL, Liquibase
⚡ Cache	Redis, Caffeine
🔒 Security	JWT (JJWT 0.13), Google OAuth2, Argon2
☁️ Cloud	AWS S3 SDK 2.x, CloudFront
💳 Payment	Stripe
🤖 AI	LangChain4j, OpenAI
📊 Observability	Micrometer, Prometheus, OpenTelemetry, Sentry, Loki
🧪 Testing	JUnit 5, Testcontainers, REST Assured, Instancio, Jacoco
📋 API	OpenAPI 3, SpringDoc 3.0, OpenAPI Generator 7
🔄 Mapping	MapStruct 1.6, Lombok
🚢 Deployment	Docker, Taskfile-based deployment, VPS hosting

---

📚 Guides & Features

📄 Document	📝 Description
START.md	IDE setup, Docker-only mode, troubleshooting
FEATURES.md	How the database, object storage, and Redis cache are wired together — with free-tier provider options (Supabase, Upstash) and all env vars explained
CONTRIBUTING.md	How to contribute, PR guidelines, branching
SECURITY.md	Security policy and vulnerability reporting
CODE_OF_CONDUCT.md	Community standards and expected behaviour
LICENSE	CC BY-NC 4.0 — free for educational use, commercial use requires permission

---

📁 Project Structure

src/main/java/com/zufar/icedlatte/
├── 🔒 security/       # JWT auth, Google OAuth2, registration, login
├── 🔑 auth/           # Google OAuth2 callback, auth redirects
├── 👤 user/           # User profile management
├── 📦 product/        # Product catalog
├── 🛒 cart/           # Shopping cart
├── 📋 order/          # Orders
├── 💳 payment/        # Stripe payment, webhooks
├── ⭐ review/         # Product reviews, ratings, AI moderation
├── ❤️ favorite/       # Favorites list
├── 📧 email/          # Email verification & notifications
├── 📁 filestorage/    # AWS S3 file upload/download
├── 📊 observability/  # Telemetry, Sentry integration
├── 🔧 common/         # Shared utilities, validation, monitoring
└── 🚀 astartup/       # Startup data migration

---

🚢 Deployment

🚫 No Kubernetes, no cloud-managed services — the app ships as a Docker image to a VPS.

Deployment is managed via Taskfile. The typical flow:

• task build — build Docker image for ARM64 (server architecture)
• task push — push to Docker Hub
• task sync-compose — copy compose file to remote server
• task deploy — pull and recreate container on the server
• task smoke — run smoke test against production endpoint
• task full-deploy — complete flow (build → push → sync-compose → deploy → smoke)

See Taskfile.yml for all available tasks.

---

🤝 Contributing

🎉 Contributions are welcome. Here's how to get involved:

🎯 Situation	🚀 Action
🐛 Found a bug	Open an issue with the bug label
💡 Want a feature	Start a Discussion first
👨💻 Ready to code	Pick a good first issue, comment "I'm on it"
🔧 Big change	Comment on the issue before writing code — many tickets have hidden constraints

---

🏷️ Issue labels

🏷️ Label	📝 Meaning
🟢 good first issue	Simple, well-scoped — great for first-timers
🔴 bug	Something is broken
🔵 high priority	Do this first
🟡 enhancement	Accepted improvement to an existing module
🟠 new feature	New functionality — discuss before starting
⚪ idea	Needs design discussion — don't implement yet

---

🐛 Bug reports

• 🔍 Search existing issues before opening a new one
• 📝 Clearly describe observed vs expected behaviour
• 🚀 For minor fixes, just open a PR directly

---

🔄 Pull requests

• 🎯 Keep PRs focused — one concern per PR
• ✅ Make sure mvn test passes locally before pushing
• 🔗 Reference the issue number in your PR description

---

🍴 Forking

🤝 Forks are welcome. Please share useful features back via PR so the community benefits and your fork stays easy to sync.

---

📄 License

📜 CC BY-NC 4.0 — free for educational and personal use with author attribution. Commercial use requires explicit written permission from the author (zufar.sunagatov@gmail.com).

---

📞 Contact

• 💬 Telegram community: Zufar Explained IT
• 👤 Personal Telegram: @lucky_1uck
• 📱 WhatsApp: Message me
• 📧 Email: zufar.sunagatov@gmail.com
• 🐛 Issues: GitHub Issues

❤️