@rivascva/dt-idl 1.1.191 → 1.1.193

package/docs/deployment.md

@@ -0,0 +1,136 @@
+# Deployment
+
+## Overview
+
+The platform consists of four Go microservices deployed as AWS Lambda functions in the **us-east-2** region. The mobile app communicates directly with each Lambda's function URL. Asynchronous background flows are orchestrated via AWS EventBridge Schedules and AWS Step Functions.
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────┐            ┌─────────────────────────────┐
+│  Mobile App │───────────▶│  AWS Lambda Function URLs   │
+└─────────────┘            └─────────────────────────────┘
+                                              │
+         ┌──────────────┬─────────────────────┼──────────────────┐
+         │              │                     │                  │
+         ▼              ▼                     ▼                  ▼
+┌──────────────┐ ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│ dt-market-   │ │ dt-asset-    │   │ dt-trade-    │   │ dt-user-     │
+│ service      │ │ service      │   │ service      │   │ service      │
+└──────┬───────┘ └──────┬───────┘   └──────┬───────┘   └──────┬───────┘
+       │                │                  │                   │
+       ▼                ▼                  ▼                   ▼
+ ┌───────────┐   ┌───────────┐      ┌───────────┐      ┌───────────┐
+ │  Upstash  │   │  AWS S3   │      │ Supabase  │      │ Supabase  │
+ │  (Redis)  │   │  (Images) │      │ (Postgres)│      │ (Postgres)│
+ └───────────┘   └───────────┘      └───────────┘      └───────────┘
+```
+
+---
+
+## Services & Lambda Functions
+
+All Lambda functions share these settings:
+
+- **Runtime:** Amazon Linux 2023
+- **Architecture:** ARM64
+- **Role:** `lambda-execution-role`
+- **Timeout:** 30 seconds
+- **Function URL:** Enabled w/ no auth
+
+| Service           | Lambda Function(s)                                  |
+| ----------------- | --------------------------------------------------- |
+| dt-market-service | `dt-market-service-prod`                            |
+|                   | `dt-market-service-refresh-realtime-quotes-prod`    |
+|                   | `dt-market-service-refresh-performance-quotes-prod` |
+| dt-trade-service  | `dt-trade-service-prod`                             |
+|                   | `dt-trade-service-execute-pending-orders-prod`      |
+|                   | `dt-trade-service-sync-portfolio-history-prod`      |
+| dt-user-service   | `dt-user-service-prod`                              |
+| dt-asset-service  | `dt-asset-service-prod`                             |
+
+All functions exit early if run outside of market hours (with a grace period).
+
+> **Console:** [Lambda Functions (us-east-2)](https://us-east-2.console.aws.amazon.com/lambda/home?region=us-east-2#/functions)
+
+---
+
+## CI/CD Pipeline
+
+Each service has a `.github/workflows/lambda-deploy.yaml` that triggers on:
+
+- Push to `main`
+- Manual dispatch (`workflow_dispatch`)
+
+### Build Process
+
+1. Checkout code
+2. Set up Go (version from `go.mod`)
+3. Configure Git for private modules via `GH_ACCESS_TOKEN`
+4. Cross-compile: `GOOS=linux GOARCH=arm64 go build -o bootstrap <path>`
+5. Zip: `zip function.zip bootstrap`
+6. Configure AWS credentials (us-east-2)
+7. Update Lambda environment variables
+8. Wait for config propagation
+9. Deploy new function code
+10. Wait for code propagation
+
+Services with asynchronous flows use a **matrix strategy** to deploy multiple Lambda functions from a single workflow run.
+
+### Environment Variables
+
+Each service's environment variables are managed via **GitHub Settings > Secrets and Variables** in its respective repository. The deployment workflow reads these secrets/variables at deploy time and pushes them to the Lambda function configuration.
+
+---
+
+## Scheduled Flows (Background Jobs)
+
+Background jobs are triggered by **AWS EventBridge Schedules** which invoke **AWS Step Functions** state machines.
+
+> **Console:** [EventBridge Schedules (us-east-2)](https://us-east-2.console.aws.amazon.com/scheduler/home?region=us-east-2#schedules) · [Step Functions (us-east-2)](https://us-east-2.console.aws.amazon.com/states/home?region=us-east-2#/statemachines)
+
+### dt-refresh-prices-schedule
+
+| Property     | Value                                                 |
+| ------------ | ----------------------------------------------------- |
+| **Schedule** | Every 5 minutes, 9:00 AM – 4:00 PM (America/New_York) |
+| **Target**   | `dt-refresh-prices-step-fn`                           |
+
+**Step Function Execution (sequential):**
+
+1. `dt-market-service-refresh-realtime-quotes-prod`
+2. `dt-market-service-refresh-performance-quotes-prod`
+3. `dt-trade-service-execute-pending-orders-prod`
+
+### dt-sync-portfolios-schedule
+
+| Property     | Value                                                  |
+| ------------ | ------------------------------------------------------ |
+| **Schedule** | Every 15 minutes, 9:01 AM – 4:01 PM (America/New_York) |
+| **Target**   | `dt-sync-portfolios-step-fn`                           |
+
+> The 1-minute offset (9:01 AM instead of 9:00 AM) ensures that the latest realtime quotes have already been refreshed by `dt-refresh-prices-schedule` before portfolios are synced.
+
+**Step Function Execution:**
+
+1. `dt-trade-service-sync-portfolio-history-prod`
+
+---
+
+## External Services
+
+| Service           | Provider                                                          | Plan                  | Purpose                             |
+| ----------------- | ----------------------------------------------------------------- | --------------------- | ----------------------------------- |
+| PostgreSQL        | [Supabase](https://supabase.com)                                  | Free                  | Primary relational database         |
+| Redis             | [Upstash](https://upstash.com)                                    | Fixed 250 MB ($10/mo) | Caching (quotes, etc.)              |
+| Stock Market Data | [Financial Modeling Prep](https://site.financialmodelingprep.com) | $19/mo                | Real-time & historical stock prices |
+
+---
+
+## Region & Networking
+
+- **AWS Region:** `us-east-2` (Ohio)
+- **Ingress:** Lambda function URLs are publicly accessible (auth type: `NONE`)
+- **Inter-service communication:** Services call each other via their function URLs

package/go/models/constants.go

@@ -40,6 +40,106 @@ const (
 	MarketCloseGracePeriod = 2 * time.Minute
 )
 
+var (
+	// MarketHolidays is a map of future market holidays.
+	// The key is the date of the holiday in YYYY-MM-DD format (based on the timezone specified in MarketTimezone).
+	// The value is the information about the holiday.
+	MarketHolidays = map[string]MarketHolidayInfo{
+		"2026-01-01": {
+			Name:      "New Year's Day",
+			CloseTime: "",
+		},
+		"2026-01-19": {
+			Name:      "Martin Luther King, Jr. Day",
+			CloseTime: "",
+		},
+		"2026-02-16": {
+			Name:      "Presidents' Day",
+			CloseTime: "",
+		},
+		"2026-04-03": {
+			Name:      "Good Friday",
+			CloseTime: "",
+		},
+		"2026-05-25": {
+			Name:      "Memorial Day",
+			CloseTime: "",
+		},
+		"2026-06-19": {
+			Name:      "Juneteenth National Independence Day",
+			CloseTime: "",
+		},
+		"2026-07-03": {
+			Name:      "Independence Day (Observed)",
+			CloseTime: "",
+		},
+		"2026-09-07": {
+			Name:      "Labor Day",
+			CloseTime: "",
+		},
+		"2026-11-26": {
+			Name:      "Thanksgiving Day",
+			CloseTime: "",
+		},
+		"2026-11-27": {
+			Name:      "Friday after Thanksgiving",
+			CloseTime: "13:00",
+		},
+		"2026-12-24": {
+			Name:      "Christmas Eve",
+			CloseTime: "13:00",
+		},
+		"2026-12-25": {
+			Name:      "Christmas Day",
+			CloseTime: "",
+		},
+		"2027-01-01": {
+			Name:      "New Year's Day",
+			CloseTime: "",
+		},
+		"2027-01-18": {
+			Name:      "Martin Luther King, Jr. Day",
+			CloseTime: "",
+		},
+		"2027-02-15": {
+			Name:      "Presidents' Day",
+			CloseTime: "",
+		},
+		"2027-03-26": {
+			Name:      "Good Friday",
+			CloseTime: "",
+		},
+		"2027-05-31": {
+			Name:      "Memorial Day",
+			CloseTime: "",
+		},
+		"2027-06-18": {
+			Name:      "Juneteenth National Independence Day (Observed)",
+			CloseTime: "",
+		},
+		"2027-07-05": {
+			Name:      "Independence Day (Observed)",
+			CloseTime: "",
+		},
+		"2027-09-06": {
+			Name:      "Labor Day",
+			CloseTime: "",
+		},
+		"2027-11-25": {
+			Name:      "Thanksgiving Day",
+			CloseTime: "",
+		},
+		"2027-11-26": {
+			Name:      "Friday after Thanksgiving",
+			CloseTime: "13:00",
+		},
+		"2027-12-24": {
+			Name:      "Christmas Day (Observed)",
+			CloseTime: "",
+		},
+	}
+)
+
 var (
 	// PortfolioDefaultCash is the default cash for new portfolios.
 	PortfolioDefaultCash = float64(50000)

package/go/models/structs.go

@@ -0,0 +1,12 @@
+package models
+
+// MarketHolidayInfo contains information about a market holiday.
+type MarketHolidayInfo struct {
+	// Name is the name of the holiday.
+	Name string
+	// CloseTime is the time the market closes on the holiday in a 24-hour format (HH:mm).
+	// Based on the timezone specified in MarketTimezone.
+	// For some holidays, the market may simply close early.
+	// The value will be empty if the market closes the entire day.
+	CloseTime string
+}

package/go/utils/context.go

@@ -21,6 +21,11 @@ func GetAccessTokenFromContext(ctx context.Context) *jwt.Token {
 	return token
 }
 
+// ContextWithAccessToken returns a new context with the given access token set.
+func ContextWithAccessToken(ctx context.Context, accessToken *jwt.Token) context.Context {
+	return context.WithValue(ctx, models.AccessTokenKey, accessToken)
+}
+
 // GetActorIdFromContext retrieves the actor id from the JWT access token in the given context.
 // The actor id is the subject of the JWT access token that represents the user id or service name that initiated the request.
 func GetActorIdFromContext(ctx context.Context) (string, error) {

package/go/utils/market.go

@@ -66,6 +66,25 @@ func isMarketHoursWithOpenAndCloseOffsets(now time.Time, openOffset time.Duratio
 		return false, fmt.Errorf("unable to parse the close minute: %w", err)
 	}
 
+	// check if on a market holiday
+	if holidayInfo, ok := models.MarketHolidays[now.Format("2006-01-02")]; ok {
+		if holidayInfo.CloseTime == "" {
+			// the market closes the entire day
+			return false, nil
+		} else {
+			// the market closes early, so set the close time to the holiday close time
+			holidayCloseTimeParts := strings.Split(holidayInfo.CloseTime, ":")
+			closeHour, err = strconv.Atoi(holidayCloseTimeParts[0])
+			if err != nil {
+				return false, fmt.Errorf("unable to parse the holiday close hour: %w", err)
+			}
+			closeMinute, err = strconv.Atoi(holidayCloseTimeParts[1])
+			if err != nil {
+				return false, fmt.Errorf("unable to parse the holiday close minute: %w", err)
+			}
+		}
+	}
+
 	// create the open time with the offset
 	openTime := time.Date(now.Year(), now.Month(), now.Day(), openHour, openMinute, 0, 0, loc)
 	openWithOffset := openTime.Add(openOffset)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivascva/dt-idl",
-  "version": "1.1.191",
+  "version": "1.1.193",
   "description": "Dream Trade - Interface Definition Language",
   "main": "dist/index.cjs.js",
   "module": "dist/index.esm.js",