Notes in the Cloud is a microservice-based platform for notes, todos, reminders, notifications, and note sharing.

For setup and running instructions, use the infrastructure repository:

https://github.com/notes-in-the-cloud/notes-cloud-infrastructure

That repository contains the Kubernetes manifests, database migrations setup, NodePort configuration, and the scripts for starting the whole project.

When the project is started through the infrastructure setup:

Frontend: http://localhost:8080
Gateway:  http://localhost:8090

The browser should communicate with the system through the API Gateway.

Frontend -> API Gateway -> Internal Services

Internal services should not be called directly by the browser.

Frontend
   |
   v
API Gateway
   |
   +--> Auth Service
   +--> Notes Service
   +--> Todo Service
   +--> Reminder Service
   +--> Sharing Service
   +--> PostgreSQL

Inside Kubernetes, services communicate by service name:

http://auth-service:8081
http://notes-service:8082
http://sharing-service:8083
http://reminder-service:8084
http://todo-service:8085
http://api-gateway:8090

The gateway is exposed locally on:

http://localhost:8090

The frontend should use the gateway as the API entry point:

http://localhost:8090/api/v1

Protected requests use:

Authorization: Bearer <access_token>

The frontend is exposed locally on:

http://localhost:8080

Public shared notes are opened through the frontend:

http://localhost:8080/shared/{token}

The frontend config should point API calls and WebSocket connections to the gateway:

API_BASE_URL=http://localhost:8090/api/v1
GATEWAY_BASE_URL=http://localhost:8090
WS_REMINDERS_URL=ws://localhost:8090/ws

Real-time reminder notifications go through the gateway.

Frontend
   |
   | WebSocket
   v
API Gateway
   ^
   | internal HTTP push
Reminder Service

The frontend connects to:

ws://localhost:8090/ws?token=<access_token>

The reminder service sends internal notification pushes to the gateway.

PostgreSQL is created and initialized through the infrastructure and migrator setup.

The migrator creates and updates the database schema through SQL migrations.

Typical database connection inside Kubernetes:

Host: postgres
Port: 5432
Database: notes_cloud
User: notes_cloud_user

The services use environment variables such as:

DB_HOST=postgres
DB_PORT=5432
POSTGRES_DB=notes_cloud
DB_USER=notes_cloud_user
DB_PASSWORD=notes_cloud_password

Services expose health endpoints for Kubernetes probes.

Common custom endpoints:

/healthz
/readyz

/healthz checks if the application is alive.

/readyz checks if the service is ready, usually including a database check.

Some services also expose Spring Boot Actuator endpoints:

/actuator/health
/actuator/health/liveness
/actuator/health/readiness

• User registration and login
• JWT authentication and refresh tokens
• OAuth login support
• Notes CRUD
• Todo lists and todo tasks
• Reminders
• In-app notifications
• Real-time WebSocket notifications
• Public note sharing through secure tokens
• PostgreSQL persistence
• Kubernetes deployment

Use the infrastructure repository:

https://github.com/notes-in-the-cloud/notes-cloud-infrastructure

General flow:

git clone https://github.com/notes-in-the-cloud/notes-cloud-infrastructure.git
cd notes-cloud-infrastructure
./setup.sh

After the setup finishes, open:

http://localhost:8080

The gateway should be available at:

http://localhost:8090

• The frontend should call only the API Gateway.
• Internal services communicate through Kubernetes service names.
• Do not use localhost for service-to-service communication inside Kubernetes.
• localhost:8080 is for the frontend from the host machine.
• localhost:8090 is for the gateway from the host machine.
• CORS should be handled by the API Gateway.
• Public share links should point to the frontend, not directly to the sharing service.