fsi-banking-mobile

Files (122)

• SKILL.md
• SKILL_ja.md
• cdk-nag-test.template.ts · assets/
• account-opening-completed.png · assets/images/app-guide/
• account-opening-confirmation.png · assets/images/app-guide/
• account-opening-form.png · assets/images/app-guide/
• admin-account-review.png · assets/images/app-guide/
• admin-approval-form.png · assets/images/app-guide/
• admin-credentials-issued.png · assets/images/app-guide/
• admin-processing.png · assets/images/app-guide/
• admin-transaction-events.png · assets/images/app-guide/
• admin-user-credentials.png · assets/images/app-guide/
• app-home-screen.png · assets/images/app-guide/
• app-security-home.png · assets/images/app-guide/
• demo-user-dashboard.png · assets/images/app-guide/
• demo-user-selection.png · assets/images/app-guide/
• deployment-output.png · assets/images/app-guide/
• transfer-completed-dashboard.png · assets/images/app-guide/
• transfer-confirmation.png · assets/images/app-guide/
• transfer-dashboard.png · assets/images/app-guide/
• transfer-input-form.png · assets/images/app-guide/
• user-dashboard.png · assets/images/app-guide/
• user-login-screen.png · assets/images/app-guide/
• mobile-banking-arch-CQRS.png · assets/images/
• mobile-banking-arch-event-sourcing.png · assets/images/
• mobile-banking-arch-overview.png · assets/images/
• mobile-banking-arch-readme-vs-monolice-microservices.png · assets/images/
• mobile-banking-arch-resilience.png · assets/images/
• mobile-banking-arch-saga-corebanking.png · assets/images/
• mobile-banking-arch-saga-pattern.png · assets/images/
• mobile-banking-arch-transaction-and-consistency.png · assets/images/
• mobile-banking-arch-transaction-outbox-pattern.png · assets/images/
• .gitignore · assets/sample-cdk/
• SECURITY_NOTICE.md · assets/sample-cdk/
• app.ts · assets/sample-cdk/bin/
• cdk.json · assets/sample-cdk/
• jest.config.js · assets/sample-cdk/
• kms-construct.ts · assets/sample-cdk/lib/constructs/
• package-lock.json · assets/sample-cdk/lib/frontend/
• package.json · assets/sample-cdk/lib/frontend/
• config.json · assets/sample-cdk/lib/frontend/public/
• index.html · assets/sample-cdk/lib/frontend/public/
• manifest.json · assets/sample-cdk/lib/frontend/public/
• App.css · assets/sample-cdk/lib/frontend/src/
• App.js · assets/sample-cdk/lib/frontend/src/
• LoginForm.js · assets/sample-cdk/lib/frontend/src/components/auth/
• ProtectedRoute.js · assets/sample-cdk/lib/frontend/src/components/auth/
• LoadingSpinner.js · assets/sample-cdk/lib/frontend/src/components/common/
• BalanceCard.js · assets/sample-cdk/lib/frontend/src/components/dashboard/
• QuickActions.js · assets/sample-cdk/lib/frontend/src/components/dashboard/
• TransactionChart.js · assets/sample-cdk/lib/frontend/src/components/dashboard/
• TransactionHistory.js · assets/sample-cdk/lib/frontend/src/components/dashboard/
• AccountOpeningForm.js · assets/sample-cdk/lib/frontend/src/components/forms/
• AuthenticatedLayout.js · assets/sample-cdk/lib/frontend/src/components/layout/
• Footer.js · assets/sample-cdk/lib/frontend/src/components/layout/
• Header.js · assets/sample-cdk/lib/frontend/src/components/layout/
• TransferConfirmation.js · assets/sample-cdk/lib/frontend/src/components/transfer/
• TransferInputForm.js · assets/sample-cdk/lib/frontend/src/components/transfer/
• api.js · assets/sample-cdk/lib/frontend/src/config/
• accountOpeningAPI.js · assets/sample-cdk/lib/frontend/src/features/accountOpening/
• …and 62 more

SKILL.md (first lines)

# FSI Mobile Banking (Resilience - Modern Architecture)

## Workload Overview

This reference architecture models a **mobile / online banking application** and
was built to demonstrate the value of a microservices architecture from a
**resilience** perspective. It covers three core banking functions — **account
opening (口座開設)**, **balance inquiry (残高照会)**, and **fund transfer (振込)** —
and is intended as a general-purpose, highly available and scalable pattern that
applies to mission-critical systems beyond the financial sector.

The workload is delivered as three AWS CDK stacks:

- **OnlineBankingAppFrontendStack** — a React SPA served through Amazon S3,
  Amazon CloudFront, and AWS WAF.
- **OnlineBankingAppBackendStack** — a set of serverless microservices on AWS
  Lambda with Amazon DynamoDB as the main data store, fronted by Amazon API
  Gateway, and coordinated through Amazon EventBridge and Amazon SQS.
- **TemporaryCoreBankingSystemStack** — a mock ("temporary") core-banking API
  that stands in for an existing core-banking (勘定系) system (account, balance,
  transaction, and customer management).

Account opening and fund transfer are processed **asynchronously**: a request is
accepted, and state changes are recorded as events (an audit trail) using
**Event Sourcing**. To keep calls into the core-banking API consistent, a
**Transaction Outbox** is used, and retry logic is embedded inside the Lambda
functions. The sample was developed with Kiro and Amazon Q Developer, largely
through "vibe coding" from an architecture diagram.

The companion core-banking (勘定系) reference architecture also uses the Saga
pattern with compensating transactions; this mobile-banking sample intentionally
adopts a *different* set of distributed-system patterns to illustrate an
alternative approach. See `references/architecture.md` for full detail, the app
walkthrough, and multi-region considerations.

## Best Practices and Key Components

### Best Practices

- MUST: Encrypt all data stores with AWS KMS customer-managed keys — DynamoDB
  tables, Lambda environment variables, S3 buckets, and SQS queues all use a
  customer-managed key (FISC 実3 / 実13 / 実30).
- MUST: Enable automatic KMS key rotation and design the key policy for
  segregation of duties (separating the key administrator from the data owner).
- MUST: Enforce TLS 1.2 or higher at API Gateway and CloudFront, and require SSL
  on S3 buckets and SQS queues (`enforceSSL`).
- MUST: Enable DynamoDB Point-in-Time Recovery (PITR) on tables holding event
  and audit data (FISC 実6 / 実39).
- MUST: Guard the write path with the Transaction Outbox pattern so a database
  update and an event publication commit atomically, then relay the event to
  external systems from the outbox table.
- MUST: Record every state change as an immutable event in an event store
  (Event Sourcing) to satisfy strict audit-trail requirements for financial
  systems.
- MUST: Ensure idempotency for external (core-banking) API calls, since
  asynchronous retries and at-least-once delivery can reproduce a message.
- MUST: Manage the JWT signing secret in AWS Secrets Manager rather than in code
  or plaintext environment variables.
- MUST: Attach AWS WAF to API Gateway (rate-based rule plus AWS managed rule
  groups: Common, KnownBadInputs, Linux) and to CloudFront.
- SHOULD: Apply the principle of least privilege — give each Lambda function its
  own IAM role scoped to the specific tables, indexes, event bus, and keys it
  needs.
- SHOULD: Separate withdrawal and deposit into independent services so a failure
  in one is localized and does not affect the other.
- SHOULD: Attach a dead-letter queue (DLQ) with a bounded receive count
  (maxReceiveCount = 3) to each SQS queue so failed processing is retried and
  captured for investigation.
- SHOULD: Enforce API Gateway usage plans with per-key throttling and daily
  quotas, and require an API Key on each method.
- SHOULD: Enable API Gateway access logging, execution logging, X-Ray tracing,
  and CloudWatch metrics, and consolidate logs in CloudWatch Logs.
- SHOULD: Restrict the core-banking API to internal callers using IAM
  authorization plus an API Key and a resource policy scoped to the account and
  region.
- PREFER: Use CloudFront Origin Access Control (OAC) over the older Origin
  Access Identity (OAI) for S3 origins.
- PREFER: Use EventBridge as the integration backbone so additional asynchronous
  fan-out processing (e.g. AI-based identity-document review, risk scoring,
  human review, customer notification) can be added without changing existing
  services.
- MAY: For multi-region resilience without a custom domain, use a CloudFront
  Origin Group with S3 Cross-Region Replication to fail over between a primary
  and secondary region; for production with a custom domain, use Route 53
  Application Recovery Controller or a Standby-Takes-Over-Primary (STOP) design.
- MAY: Enable DynamoDB Global Tables with strong consistency to synchronize
  event state across regions, then re-drive stalled events after a region
  switch.
- MUST NOT: Assume real-time consistency — because processing is asynchronous
  and eventually consistent, add explicit handling when an operation needs an
  immediate confirmed state.
- WILL: A monolith stops the whole service when one component fails and must be
  scaled as a unit, whereas microservices keep other services running and can be
  scaled independently, localizing fault impact.
- WILL: In this sample the mail-delivery Lambda is a stub that only writes log
  output; real email/notification delivery is expected to call a separate
  external system.
- MUST: Apply cdk-nag's AwsSolutionsChecks (via Aspects) to every CDK stack built from this skill, and gate CI (jest etc.) on zero unsuppressed AwsSolutions-* findings; suppress exceptions only with an explicit reason via NagSuppressions (see references/cdk-nag.md).

### Key Components

#### Frontend Delivery (OnlineBankingAppFrontendStack)

- **Component Overview**: Hosts the React single-page application. Static content
  is stored in a private, versioned, KMS-encrypted S3 bucket and served through a
  CloudFront distribution (OAC, redirect-to-HTTPS, TLS 1.2+ minimum, Japan-only
  geo-restriction). Access logs go to a dedicated S3 log bucket; a CloudFront WAF
  Web ACL is created when deployed to us-east-1.
- **Assumed AWS Services**: Amazon S3, Amazon CloudFront, AWS WAF, AWS KMS, AWS
  Systems Manager Parameter Store.

#### API Layer (OnlineBankingAppBackendStack)

- **Component Overview**: A single Amazon API Gateway REST API ("Banking API")
  exposes customer, auth, admin, balance, and transfer endpoints. It uses a JWT
  Lambda token authorizer for protected routes, per-audience API Keys
  (customer / admin / auth) with usage plans, request validation, access/exec
  logging, and a regional WAF Web ACL.
- **Assumed AWS Services**: Amazon API Gateway, AWS Lambda (authorizer), AWS WAF,

From aws-samples/sample-fsi-reference-architecture-jp, MIT-0.

More from aws-samples/sample-fsi-reference-architecture-jp