⚡ Quick Cheat Sheet

Quick reference of commands and project stages for OnlineStore.

🎯 Current Stage

Stage 4-5: Client integration phase (Stage 3 core DoD closed)

Next steps:

✅ Stage 1 Backend Core is implemented and documented as meeting DoD.
✅ Stage 2 Telegram Bot is implemented and documented as meeting DoD.
✅ Stage 3 Admin Panel core DoD is closed (OIDC + admin API + STOMP + responsive theme); depth follow-ups remain in TASK.md.
🟨 Stage 4 Store Frontend exists as a Next.js prototype; mocked data must be replaced with backend integration before DoD.
🟨 Stage 5 Mobile App exists as an Expo/React Native prototype; backend/auth/push integration must be hardened before DoD.
⏳ Stage 6 Testing starts after the selected client flows are integrated enough for useful E2E coverage.

Recommended focus: choose Stage 4 or Stage 5 as the next formal milestone, finish its backend/auth integration, then advance to Stage 6 testing.

Details: docs/getting-started.md

🛠️ Main Commands

Infrastructure

task init          # Project initialization
task up            # Start all services
task down          # Stop services
task restart       # Restart services
task logs          # Show logs
task clean         # Delete all data

Services

task gateway-run   # API Gateway :8080
task backend-run   # Backend :8081
task bot-run       # Telegram Bot :8082
task admin-run     # Admin Panel :4200
task store-run     # Store Frontend :3000

Monitoring

task monitoring    # Grafana → http://localhost:3001
task tracing       # Jaeger → http://localhost:16686
task prometheus    # Prometheus → http://localhost:9090

Database

task db-migrate    # Apply migrations
task db-psql       # Connect to PostgreSQL
task db-reset      # Reset DB (DANGEROUS!)

Testing

task test          # Backend tests (current)
task test-backend  # Backend tests
task test-bot      # Telegram Bot tests
task test-e2e      # E2E tests

# Dependency audit
mvn org.owasp:dependency-check-maven:check
npm audit --audit-level=high

Build

task build         # Build all services
task docker-build  # Build Docker images

🌐 Service Access

Service	URL	Credentials
API Gateway	http://localhost:8080	JWT token
Backend API	http://localhost:8081	JWT token
Telegram Bot	http://localhost:8082	Telegram update transport
Store Frontend	http://localhost:3000	Keycloak
Admin Panel	http://localhost:4200	Keycloak
Keycloak	http://localhost:8180	admin / (from .env)
RabbitMQ	http://localhost:15672	admin / (from .env)
MinIO	http://localhost:9001	minioadmin / (from .env)
Grafana	http://localhost:3001	admin / (from .env)
Jaeger	http://localhost:16686	-
Prometheus	http://localhost:9090	-
Elasticsearch	http://localhost:9200	-
Vault	http://localhost:8200	(from .env)

📋 Project Stages

#	Stage	Duration	File
0	Infrastructure	1 week	✅ Implemented; stage-0-infrastructure.md
1	Backend Core	4 weeks	✅ Implemented; stage-1-backend-core.md
2	Telegram Bot	2 weeks	✅ Implemented; stage-2-telegram-bot.md
3	Admin Panel	3 weeks	✅ Core DoD closed; stage-3-admin-panel.md
4	Store Frontend	3 weeks	🟨 Prototype; stage-4-store-frontend.md
5	Mobile App	2 weeks	🟨 Prototype; stage-5-mobile-app.md
6	Testing	2 weeks	⏳ Pending; stage-6-testing.md
7	Deployment	1 week	⏳ Pending; stage-7-deploy.md

Total: ~18 weeks (~4.5 months)

🏗️ Project Structure

OnlineStore/
├── api-gateway/           # Spring Cloud Gateway :8080
├── backend/               # Modular Monolith :8081
│   ├── common/
│   ├── catalog-module/
│   ├── orders-module/
│   ├── users-module/
│   ├── payments-module/
│   ├── shipping-module/
│   ├── notifications-module/
│   ├── search-module/
│   └── application/
├── telegram-bot/          # Telegram Bot :8082
├── store-frontend/        # Next.js :3000
├── admin-panel/           # Angular :4200
├── mobile-app/            # React Native
├── infrastructure/
│   ├── docker/
│   ├── k8s/
│   └── nginx/
└── docs/
    ├── architecture/      # Diagrams and ADR
    ├── development/       # Project plan
    └── stages/            # Detailed stage plans

📚 Key Documents

Document	Purpose
../README.md	Project overview
getting-started.md	Step-by-step plan
development/plan.md	General plan and stack
architecture/overview.md	Architecture diagrams
architecture/decisions.md	Architectural decisions

🔑 Environment Variables (.env)

Required for start:

POSTGRES_PASSWORD=your_secure_password
KEYCLOAK_ADMIN_PASSWORD=your_secure_password
POSTGRES_REPLICATION_USER=replicator
POSTGRES_REPLICATION_PASSWORD=your_secure_password

For Telegram bot:

TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_WEBHOOK_URL=
TELEGRAM_WEBHOOK_SECRET_TOKEN=replace-with-a-long-random-secret
TELEGRAM_SESSION_TTL=12h
BACKEND_API_BASE_URL=http://localhost:8080
TELEGRAM_MANAGER_NOTIFICATIONS_ENABLED=true
TELEGRAM_MANAGER_CHAT_ID=-100123456789
TELEGRAM_MANAGER_CHAT_IDS=-100123456789,-100987654321
TELEGRAM_MANAGER_USER_ID=123456789
TELEGRAM_MANAGER_USER_IDS=123456789,987654321
TELEGRAM_USER_RATE_LIMIT_MAX_EVENTS=20
TELEGRAM_MANAGER_RATE_LIMIT_MAX_ACTIONS=6
BACKEND_SERVICE_AUTH_ENABLED=true
BACKEND_SERVICE_AUTH_CLIENT_ID=telegram-bot
BACKEND_SERVICE_AUTH_TOKEN_URL=http://localhost:8180/realms/online-store/protocol/openid-connect/token
BACKEND_SERVICE_AUTH_CLIENT_SECRET=telegram-bot-secret

Runbook: telegram-bot/README.md

For AI chat:

TELEGRAM_AI_ASSISTANT_ENABLED=true
OPENAI_API_KEY=sk-...
TELEGRAM_AI_RATE_LIMIT_MAX_REQUESTS=4
AI_PROVIDER=openai

For payments:

PAYMENTS_CARD_API_KEY=sk_test_...
PAYMENTS_CARD_WEBHOOK_SECRET=whsec_...
PAYPAL_CLIENT_ID=...
PAYPAL_CLIENT_SECRET=...
BANK_TRANSFER_IBAN=...

Full list: .env.example

🧪 Testing API Gateway

Health Check

curl http://localhost:8080/actuator/health

Public API (no auth)

curl http://localhost:8080/api/v1/public/products

Get token from Keycloak

TOKEN=$(curl -X POST http://localhost:8180/realms/online-store/protocol/openid-connect/token \
  -d "client_id=store-web" \
  -d "grant_type=password" \
  -d "username=testclient" \
  -d "password=password" \
  | jq -r '.access_token')

Authenticated Request

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8080/api/v1/orders

Rate Limiting Test

# Should hit rate limit after 100+ requests
for i in {1..150}; do
  curl http://localhost:8080/api/v1/public/products
done

🐛 Troubleshooting

Docker services not starting

# Check status
docker compose ps

# View logs of a specific service
docker compose logs postgres-primary

# Restart
task restart

Keycloak unavailable

# Check logs
docker compose logs keycloak

# Wait 1-2 minutes after start
# Keycloak takes a while to start

API Gateway not starting

# Ensure Redis is running
docker compose ps redis

# Check application.yml
cat api-gateway/src/main/resources/application.yml

# Run with debug logs
cd api-gateway
./mvnw spring-boot:run -Dspring-boot.run.arguments=--logging.level.org.springframework.cloud.gateway=DEBUG

PostgreSQL replication not working

# Check replication status
docker exec -it store-postgres-primary psql -U store -d online_store \
  -c "SELECT * FROM pg_stat_replication;"

# Should have one row with state=streaming

💡 Best Practices

Git Workflow

# Create feature branch
git checkout -b feature/my-feature

# Commit with conventional commits
git commit -m "feat(catalog): add product search"
git commit -m "fix(orders): resolve payment validation"
git commit -m "docs: update API documentation"

# Push
git push origin feature/my-feature

# Create Pull Request on GitHub

Database Migrations

# Run new migrations
cd backend
./mvnw flyway:migrate

# Naming: V{version}__{description}.sql
# Example: V001__create_users_table.sql

Logging

// Structured logging with trace context
log.info("Order created: orderId={}, userId={}, amount={}",
    orderId, userId, amount);

🆘 Get Help

Documentation: Read docs/ for details
GitHub Issues: Create an issue for bug reports
Team: Contact the tech lead

This cheat sheet should always be at hand! 📌

FilesExpand file tree

quick-reference.md

Latest commit

History