⬅️ Back to Architecture Index

Resources Architecture

Overview: This section documents all externalized configuration and resource files used by the Spring Boot application, including profiles, environment variables, logging, and database configuration.

Table of Contents

1. Resources Folder Purpose
2. File Mapping
3. Configuration Hierarchy
4. Environment Variables
5. Related Configuration
6. Quick Navigation

Resources Folder Purpose

The src/main/resources/ folder contains all externalized configuration that varies by environment or sensitive data injected at runtime. This keeps application behavior flexible without recompilation.

Principle: Code → Compiled once
          Configuration → Injected per environment
          Secrets → Managed externally

What Goes in Resources

✅ Configuration Files: - application.yml - Base config for all profiles - application-prod.yml - Production overrides - application-test.yml - Test overrides - application.properties - Application metadata

✅ Environment-Specific: - .env.example - Template for local development - fly.toml - Fly.io deployment config (root) - Oracle Wallet path references (to /oracle_wallet)

❌ What Does NOT Go Here: - Secrets (OAuth2 tokens, DB passwords) - use environment variables - Build artifacts - use target/ directory - Static HTML/CSS - backend is API-only; see /frontend - Java code - use src/main/java/

File Mapping

Spring Boot Configuration Files

Environment & Deployment Files

Database & Oracle Files (References)

Configuration Hierarchy

How Spring Boot Loads Configuration

Example: Database Configuration

application.yml:

spring:
  datasource:
    url: ${DB_URL}              # Placeholder - actual value from env
    username: ${DB_USER}        # Placeholder - actual value from env
    password: ${DB_PASS}        # Placeholder - actual value from env

application-test.yml:

spring:
  datasource:
    url: jdbc:h2:mem:ssp;...    # Override: H2 in-memory for tests
    driver-class-name: org.h2.Driver

Local Environment (export or .env):

export DB_URL=jdbc:oracle:thin:@localhost:1521/xe
export DB_USER=inventory_admin
export DB_PASS=secret123

Result at Runtime: - test profile → H2 (from application-test.yml) - local dev (no profile) → Oracle (from environment variables) - production → Oracle (from fly.toml secrets)

Environment Variables

Required Variables by Profile

Production (via fly.toml)

[env]
  SPRING_PROFILES_ACTIVE = "prod"
  DB_URL = "jdbc:oracle:thin:@..."
  DB_USER = "admin"
  DB_PASS = "***"
  SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_GOOGLE_CLIENT_ID = "***"
  SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_GOOGLE_CLIENT_SECRET = "***"
  TNS_ADMIN = "/path/to/wallet"

Local Development (via .env.example)

# Database (Oracle or PostgreSQL)
DB_URL=jdbc:oracle:thin:@localhost:1521/xe
DB_USER=inventory_admin
DB_PASS=password

# OAuth2
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_GOOGLE_CLIENT_ID=your_client_id
SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_GOOGLE_CLIENT_SECRET=your_secret

# Oracle Wallet (if using Oracle Autonomous DB)
TNS_ADMIN=/path/to/wallet
ORACLE_WALLET_PASSWORD=wallet_password

Testing

export SPRING_PROFILES_ACTIVE=test
# H2 database configured in application-test.yml - no DB_URL needed

How Variables Are Referenced

Pattern: ${VARIABLE_NAME} in YAML/properties files

With Default Values: ${APP_DEMO_READONLY:true} - If APP_DEMO_READONLY not set, use true as default

Example from application.yml:

app:
  demo-readonly: ${APP_DEMO_READONLY:true}   # Default: true if not set
  frontend:
    base-url: ${APP_FRONTEND_BASE_URL:https://localhost:5173}  # Default for local dev

Related Configuration

How Resources Connect to Other Documentation

Java Configuration Classes

Resources are loaded by Spring into @ConfigurationProperties and @Value fields:

See: Configuration (Java) Documentation

Oracle Wallet Integration

Database credentials are stored in Oracle Wallet instead of hardcoded:

Quick Navigation

Configuration Deep Dives

• Application YAML & Properties - Structure of base config files, which keys go where
• Environment-Specific Config - Profiles (prod/test), .env usage, how Fly.io injects variables
• Logging Configuration - Log levels by profile, where logs are written, debug logging
• Database Config & Oracle Wallet - Datasource setup, connection pools, wallet integration
• Static Resources & Templates - Why backend is API-only, frontend location

Related Architecture Documentation

• Configuration Management (Java) - Spring @Configuration classes that use these resources
• Security Architecture - OAuth2 config, authentication setup
• Testing Strategy - How test profile overrides work
• Deployment - How resources deploy to Fly.io, Docker

Common Tasks

Local Development Setup

# 1. Copy environment template
cp .env.example .env

# 2. Edit .env with your database connection
nano .env

# 3. Source variables
export $(cat .env | xargs)

# 4. Run application (no profile = uses application.yml + env vars)
mvn spring-boot:run

Run Tests

# No env vars needed - uses application-test.yml with H2
mvn clean test

Deploy to Production

# Fly.io reads fly.toml for env and SPRING_PROFILES_ACTIVE=prod
fly deploy
# Automatically uses application-prod.yml

Summary Table

Troubleshooting

Configuration Not Being Picked Up

Check: Is the right profile active?

# See active profiles in logs during startup
# Look for: "The following profiles are active: prod,test"

Solution: Set SPRING_PROFILES_ACTIVE environment variable

export SPRING_PROFILES_ACTIVE=prod
mvn spring-boot:run

Environment Variables Not Resolved

Check: Variable name matches placeholder

# In application.yml
DB_URL: ${DB_URL}

# Must export with exact name
export DB_URL="jdbc:oracle:..."

Solution: Use ${VAR_NAME:defaultValue} with defaults if variable is optional

Oracle Wallet Connection Fails

Check: TNS_ADMIN points to wallet directory

ls -la $TNS_ADMIN  # Should show sqlnet.ora, tnsnames.ora, etc.

Solution: See Database Config & Oracle Wallet

⬅️ Back to Architecture Index