# developer4949-code/stock-alert-app architecture

> Architecture diagram of the GitHub repository developer4949-code/stock-alert-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/developer4949-code/stock-alert-app
- Repository: https://github.com/developer4949-code/stock-alert-app

## Overview

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: [`src/main/java/com/example/stocksentry/service/NewsService.java`](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/NewsService.java) (News service), [`src/main/java/com/example/stocksentry/service/WatchlistService.java`](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/WatchlistService.java) (Watchlist service), [`src/main/java/com/example/stocksentry/controller/WatchlistController.java`](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/WatchlistController.java) (Watchlists), [`src/main/java/com/example/stocksentry/service/OtpService.java`](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/OtpService.java) (OTP service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_client["Clients"]
  node_node_android_client(("Android client<br/>external client"))
end

subgraph group_group_api["API Layer"]
  node_node_health_controller["Health<br/>controller"]
  node_node_news_controller["News API<br/>controller"]
  node_node_user_controller["Users<br/>controller"]
  node_node_watchlist_controller["Watchlists<br/>controller"]
end

subgraph group_group_core["Core Services"]
  node_node_news_scheduler["News job<br/>scheduler<br/>[NewsScheduler.java]"]
  node_node_news_service["News service<br/>[NewsService.java]"]
  node_node_notification_service["Notifications"]
  node_node_watchlist_service["Watchlist service"]
  node_node_user_service["User service<br/>[UserService.java]"]
  node_node_otp_service["OTP service<br/>[OtpService.java]"]
  node_node_exception{{"App error<br/>exception"}}
  node_node_app(("Spring Boot app"))
end

subgraph group_group_data["Persistence"]
  node_node_user_repo[("User repo")]
  node_node_watchlist_repo[("Watchlist repo")]
  node_node_otp_repo[("OTP repo<br/>[OtpRepository.java]")]
  node_node_alertlog_repo[("Alert log")]
end

subgraph group_group_integrations["Integrations"]
  node_node_aws_config["AWS config<br/>[AwsConfig.java]"]
  node_node_news_api(("NewsAPI<br/>external api"))
  node_node_aws_ses(("AWS SES<br/>cloud email"))
  node_node_aws_sns(("AWS SNS<br/>cloud messaging"))
  node_node_aws_dynamodb[("DynamoDB<br/>cloud datastore")]
end

node_node_android_client -->|"checks"| node_node_health_controller
node_node_android_client -->|"requests"| node_node_news_controller
node_node_android_client -->|"requests"| node_node_user_controller
node_node_android_client -->|"requests"| node_node_watchlist_controller
node_node_health_controller -->|"served by"| node_node_app
node_node_news_controller -->|"uses"| node_node_news_service
node_node_user_controller -->|"uses"| node_node_user_service
node_node_watchlist_controller -->|"uses"| node_node_watchlist_service
node_node_watchlist_controller -->|"uses"| node_node_otp_service
node_node_news_scheduler -->|"triggers"| node_node_news_service
node_node_news_service -->|"fetches"| node_node_news_api
node_node_news_service -->|"publishes"| node_node_notification_service
node_node_notification_service -->|"delivers via"| node_node_aws_sns
node_node_otp_service -->|"sends via"| node_node_aws_ses
node_node_aws_config -->|"configures"| node_node_aws_ses
node_node_aws_config -->|"configures"| node_node_aws_sns
node_node_user_service -->|"reads/writes"| node_node_user_repo
node_node_watchlist_service -->|"reads/writes"| node_node_watchlist_repo
node_node_watchlist_service -->|"reads/writes"| node_node_otp_repo
node_node_otp_service -->|"reads/writes"| node_node_otp_repo
node_node_news_service -->|"writes"| node_node_alertlog_repo
node_node_user_repo -->|"backed by"| node_node_aws_dynamodb
node_node_watchlist_repo -->|"backed by"| node_node_aws_dynamodb
node_node_otp_repo -->|"backed by"| node_node_aws_dynamodb
node_node_alertlog_repo -->|"backed by"| node_node_aws_dynamodb
node_node_news_service -->|"throws"| node_node_exception
node_node_watchlist_service -->|"throws"| node_node_exception

click node_node_health_controller "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/HealthController.java"
click node_node_news_controller "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/NewsController.java"
click node_node_user_controller "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/UserController.java"
click node_node_watchlist_controller "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/WatchlistController.java"
click node_node_news_scheduler "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/NewsScheduler.java"
click node_node_news_service "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/NewsService.java"
click node_node_notification_service "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/NotificationService.java"
click node_node_watchlist_service "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/WatchlistService.java"
click node_node_user_service "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/UserService.java"
click node_node_otp_service "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/OtpService.java"
click node_node_user_repo "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/UserRepository.java"
click node_node_watchlist_repo "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/WatchlistRepository.java"
click node_node_otp_repo "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/OtpRepository.java"
click node_node_alertlog_repo "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/AlertLogRepository.java"
click node_node_aws_config "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/config/AwsConfig.java"
click node_node_exception "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/exception/StockSentryException.java"
click node_node_app "https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/StockSentryApplication.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_android_client toneBlue
class node_node_health_controller,node_node_news_controller,node_node_user_controller,node_node_watchlist_controller toneAmber
class node_node_news_scheduler,node_node_news_service,node_node_notification_service,node_node_watchlist_service,node_node_user_service,node_node_otp_service,node_node_exception,node_node_app toneMint
class node_node_user_repo,node_node_watchlist_repo,node_node_otp_repo,node_node_alertlog_repo toneRose
class node_node_aws_config,node_node_news_api,node_node_aws_ses,node_node_aws_sns,node_node_aws_dynamodb toneIndigo
```

## Components

### Clients

External callers and operational probes

- **Android client**: external client · Primary consumer of the backend APIs

### API Layer

Spring MVC entry points

- [Health](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/HealthController.java): controller · Service readiness endpoint · `src/main/java/com/example/stocksentry/controller/HealthController.java`
- [News API](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/NewsController.java): controller · News-related HTTP endpoints · `src/main/java/com/example/stocksentry/controller/NewsController.java`
- [Users](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/UserController.java): controller · User account and access endpoints · `src/main/java/com/example/stocksentry/controller/UserController.java`
- [Watchlists](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/controller/WatchlistController.java): controller · Watchlist CRUD and sharing endpoints · `src/main/java/com/example/stocksentry/controller/WatchlistController.java`

### Core Services

Business orchestration and scheduled execution

- [News job](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/NewsScheduler.java): scheduler · Periodic trigger for news ingestion · `src/main/java/com/example/stocksentry/service/NewsScheduler.java`
- [News service](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/NewsService.java): service · Fetches and interprets stock-related news · `src/main/java/com/example/stocksentry/service/NewsService.java`
- [Notifications](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/NotificationService.java): service · Publishes alerts to downstream channels · `src/main/java/com/example/stocksentry/service/NotificationService.java`
- [Watchlist service](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/WatchlistService.java): service · Manages watchlist rules and sharing state · `src/main/java/com/example/stocksentry/service/WatchlistService.java`
- [User service](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/UserService.java): service · Handles user lifecycle and lookup · `src/main/java/com/example/stocksentry/service/UserService.java`
- [OTP service](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/service/OtpService.java): service · Generates and verifies share passcodes · `src/main/java/com/example/stocksentry/service/OtpService.java`
- [App error](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/exception/StockSentryException.java): exception · Custom application exception boundary · `src/main/java/com/example/stocksentry/exception/StockSentryException.java`
- [Spring Boot app](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/StockSentryApplication.java): application · Application entry point · `src/main/java/com/example/stocksentry/StockSentryApplication.java`

### Persistence

Repository boundary and stored state

- [User repo](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/UserRepository.java): repository · User persistence boundary · `src/main/java/com/example/stocksentry/repository/UserRepository.java`
- [Watchlist repo](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/WatchlistRepository.java): repository · Watchlist persistence boundary · `src/main/java/com/example/stocksentry/repository/WatchlistRepository.java`
- [OTP repo](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/OtpRepository.java): repository · Stores OTP verification state · `src/main/java/com/example/stocksentry/repository/OtpRepository.java`
- [Alert log](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/repository/AlertLogRepository.java): repository · Persists alert outcomes · `src/main/java/com/example/stocksentry/repository/AlertLogRepository.java`

### Integrations

AWS and third-party external dependencies

- [AWS config](https://github.com/developer4949-code/stock-alert-app/blob/ss-backend/src/main/java/com/example/stocksentry/config/AwsConfig.java): config · Central AWS client wiring · `src/main/java/com/example/stocksentry/config/AwsConfig.java`
- **NewsAPI**: external api · Financial news source
- **AWS SES**: cloud email · Email delivery for OTP messages
- **AWS SNS**: cloud messaging · Downstream notification delivery
- **DynamoDB**: cloud datastore · Backing store for application data

## Connections

- 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
