How developer4949-code/stock-alert-app works
1. What this repository is
- This repo contains the Spring Boot backend for the StockSentry/stock-alert system. The README describes an Android client, but the code here is the server-side API, scheduler, and integration layer that powers it.
2. Runtime and build boundary
- The app starts from StockSentryApplication and is built with Gradle on Java 17+.
- src/main/resources/application.properties is the main runtime configuration surface for API keys, AWS credentials, and service endpoints.
3. API layer
- The controller package exposes the HTTP entry points:
- HealthController for service checks.
- NewsController for news-related endpoints.
- UserController for user access and account flows.
- WatchlistController for watchlist CRUD and sharing actions.
- These controllers are the external boundary for the Android app or any other client.
4. Service layer: core business logic
- The service package holds the orchestration logic:
- WatchlistService manages watchlist rules and sharing state.
- UserService handles user lifecycle and lookup.
- OtpService generates/verifies one-time passcodes for secure sharing.
- NewsService fetches and interprets news for stock events.
- NotificationService sends alert notifications to downstream channels.
- NewsScheduler periodically triggers news ingestion without a client request.
5. Data flow for alerts
- The main alert pipeline is:
- scheduler or request triggers NewsService
- news is fetched from an external source
- relevant stock/event keywords are matched
- NotificationService publishes the result
- alert outcomes are likely recorded via repositories such as AlertLogRepository
- This makes the backend both a polling engine and an API server.
6. Secure watchlist sharing flow
- Sharing is not just a direct copy of data; it is mediated by OTP:
- a share request enters through WatchlistController
- OtpService creates/verifies the passcode
- OtpRepository stores verification state
- AwsConfig likely wires AWS email delivery for OTP messages
- The DTO ShareRequest represents this boundary between API input and business logic.
7. Persistence boundary
- The repository package contains the data-access abstraction:
- UserRepository
- WatchlistRepository
- OtpRepository
- AlertLogRepository
- The README mentions DynamoDB, so these repositories are likely the adapter layer to AWS-backed persistence, even though the concrete implementation is not visible from the file tree.
8. Domain models and transport models
- The dto package defines the request/response shapes used across controllers and services:
- User
- Watchlist
- ShareRequest
- NewsResponse
- These objects form the contract between the API layer and the business layer, keeping the controllers thin.
9. AWS and external integrations
- config/AwsConfig is the central configuration boundary for AWS clients.
- Based on the README, the system is designed to integrate with:
- NewsAPI for financial news ingestion
- AWS SES for OTP email delivery
- AWS SNS for notification delivery
- AWS DynamoDB for persistence
- optionally AWS Pinpoint for analytics
- The repo is structured so these services are hidden behind service/repository abstractions rather than leaking into controllers.
10. Error handling
- StockSentryException is the custom application exception type.
- This suggests a centralized error path for business-rule failures such as invalid OTPs, missing watchlists, or failed news/notification operations.
11. Operational endpoints and readiness
- HealthController provides a simple operational check for deployment environments like Elastic Beanstalk.
- This is the minimal external signal used to verify the backend is alive before the client depends on it.
12. Testing surface
- StockSentryApplicationTests is a lightweight integration test entry point, indicating the repository is set up for Spring Boot context verification rather than deep unit-test coverage in this snapshot.
13. How to draw the architecture
- The clean diagram should show:
- Android client / external clients on the left
- Spring Boot controllers as the API boundary
- services in the middle as the orchestration layer
- repositories below as the persistence boundary
- AWS/NewsAPI on the right as external dependencies
- scheduler as a parallel trigger into the service layer
- The key architectural idea is that news polling, watchlist management, OTP sharing, and notifications are all coordinated inside the backend, with the client only consuming APIs and receiving alerts.
Main entry points: NewsService.java News service · WatchlistService.java Watchlist service · WatchlistController.java Watchlists · OtpService.java OTP service
Components 22
Clients
External callers and operational probes
- Android client · Primary consumer of the backend APIs
API Layer
Spring MVC entry points
- Health · Service readiness endpoint
src/main/java/com/example/stocksentry/controller/HealthController.java - News API · News-related HTTP endpoints
src/main/java/com/example/stocksentry/controller/NewsController.java - Users · User account and access endpoints
src/main/java/com/example/stocksentry/controller/UserController.java - Watchlists · Watchlist CRUD and sharing endpoints
src/main/java/com/example/stocksentry/controller/WatchlistController.java
Core Services
Business orchestration and scheduled execution
- News job · Periodic trigger for news ingestion
src/main/java/com/example/stocksentry/service/NewsScheduler.java - News service · Fetches and interprets stock-related news
src/main/java/com/example/stocksentry/service/NewsService.java - Notifications · Publishes alerts to downstream channels
src/main/java/com/example/stocksentry/service/NotificationService.java - Watchlist service · Manages watchlist rules and sharing state
src/main/java/com/example/stocksentry/service/WatchlistService.java - User service · Handles user lifecycle and lookup
src/main/java/com/example/stocksentry/service/UserService.java - OTP service · Generates and verifies share passcodes
src/main/java/com/example/stocksentry/service/OtpService.java - App error · Custom application exception boundary
src/main/java/com/example/stocksentry/exception/StockSentryException.java - Spring Boot app · Application entry point
src/main/java/com/example/stocksentry/StockSentryApplication.java
Persistence
Repository boundary and stored state
- User repo · User persistence boundary
src/main/java/com/example/stocksentry/repository/UserRepository.java - Watchlist repo · Watchlist persistence boundary
src/main/java/com/example/stocksentry/repository/WatchlistRepository.java - OTP repo · Stores OTP verification state
src/main/java/com/example/stocksentry/repository/OtpRepository.java - Alert log · Persists alert outcomes
src/main/java/com/example/stocksentry/repository/AlertLogRepository.java
Integrations
AWS and third-party external dependencies
- AWS config · Central AWS client wiring
src/main/java/com/example/stocksentry/config/AwsConfig.java - NewsAPI · Financial news source
- AWS SES · Email delivery for OTP messages
- AWS SNS · Downstream notification delivery
- DynamoDB · Backing store for application data
Connections 27
- Android client → Health: checks · Operational readiness probe
- Android client → News API: requests · Client-driven news access
- Android client → Users: requests · Client-driven user flows
- Android client → Watchlists: requests · Client-driven watchlist flows
- Health → Spring Boot app: served by · Managed by the Spring Boot application
- News API → News service: uses · Delegates news operations
- Users → User service: uses · Delegates user operations
- Watchlists → Watchlist service: uses · Delegates watchlist operations
- Watchlists → OTP service: uses · Coordinates secure sharing
- News job → News service: triggers · Periodic ingestion trigger
- News service → NewsAPI: fetches · Retrieves external market news
- News service → Notifications: publishes · Hands matched events to alert delivery
- Notifications → AWS SNS: delivers via · Sends downstream alerts
- OTP service → AWS SES: sends via · Delivers OTP messages by email
- AWS config → AWS SES: configures · Wires SES client
- AWS config → AWS SNS: configures · Wires SNS client
- User service → User repo: reads/writes · User persistence access
- Watchlist service → Watchlist repo: reads/writes · Watchlist persistence access
- Watchlist service → OTP repo: reads/writes · OTP-backed sharing state
- OTP service → OTP repo: reads/writes · Stores and verifies passcodes
- News service → Alert log: writes · Records alert outcomes
- User repo → DynamoDB: backed by · Persisted in DynamoDB
- Watchlist repo → DynamoDB: backed by · Persisted in DynamoDB
- OTP repo → DynamoDB: backed by · Persisted in DynamoDB
- Alert log → DynamoDB: backed by · Persisted in DynamoDB
- News service → App error: throws · Business rule and integration failures
- Watchlist service → App error: throws · Invalid watchlist and share flows