Learning Bank

Learning Bank is a parent-supervised teaching application that helps children learn deposits, savings, transfers, and spending visibility through a safe online banking style experience.

Repository Overview

• Backend API: src/LearningBank.Api
• Domain model and business rules: src/LearningBank.Domain
• Persistence and EF Core implementation: src/LearningBank.Infrastructure
• Frontend web app: src/learning-bank-web
• Azure infrastructure as code (Bicep): infra/azure
• Tests: tests
• Component documentation: docs

Detailed Documentation

• Documentation index: docs/README.md
• Environment setup guide: docs/environment-setup.md
• Domain documentation: docs/domain.md
• Infrastructure documentation: docs/infrastructure.md
• API documentation: docs/api.md
• Web documentation: docs/web.md

Architecture at a Glance

flowchart LR
    U[User Browser] --> W[Next.js Web App]
    W --> BFF[Route Handlers BFF]
    BFF --> API[ASP.NET Core API /api/v1]
    API --> DOM[Domain Rules and Services]
    API --> INF[Infrastructure Repositories]
    INF --> DB[(SQLite or SQL Server)]

Loading

Core Product Flows

Child experience

• View checking and savings balances.
• View transaction history per account.
• Submit deposits with category selection.
• Transfer checking to savings when funds exist.
• Request savings to checking transfer for parent review.

Parent experience

• View linked children.
• Add child accounts.
• Submit deposits and withdrawals for linked children.
• Review pending savings withdrawal requests.
• Manage category catalog with archive and child-allowed controls.
• Configure family display preferences for currency and date formatting.

Platform admin experience

• Access a dedicated internal admin surface at /admin.
• Manage users with grouped parent, linked-parent, and child views.
• Query users, disable or re-enable accounts, and delete accounts (when runtime policy allows it).
• Review platform health and runtime flags.
• Update guarded non-secret runtime settings.

Screenshots

Sign-in page

The sign-in page keeps the entry point simple and routes authenticated users into the correct parent or child experience.

Child dashboard

Children start with a focused dashboard that shows balances, actions, and transaction history in one place.

Parent dashboard

Parents can review each linked child, balances, and pending transfer activity from the dashboard view.

Settings page

Families can manage currency and date presentation alongside the deposit category catalog.

Penny guide

Penny helps children learn the dashboard the first time they log in, and can be reopened whenever they need help.

Local Development Setup

Prerequisites

• .NET SDK 10
• Node.js 22 LTS
• npm

Environment setup

1. Copy src/learning-bank-web/.env.example to src/learning-bank-web/.env.local.
2. Fill all required OIDC and auth values.
3. Follow provider setup instructions in docs/environment-setup.md.

Required variables are documented in src/learning-bank-web/.env.example and explained in detail in docs/environment-setup.md.

Environment values required for local startup:

• AUTH_SECRET
• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• AZURE_AD_CLIENT_ID
• AZURE_AD_CLIENT_SECRET
• NEXT_PUBLIC_API_URL
• NEXTAUTH_URL

Start both services (recommended)

./dev.ps1

Service URLs:

• API: https://localhost:5001
• Web: http://localhost:3000

Start services manually

API:

cd src/LearningBank.Api
dotnet run

Web:

cd src/learning-bank-web
npm install
npm run dev

Build and Test

From repository root:

dotnet build
dotnet test

From src/learning-bank-web:

npm run typecheck
npm run test
npm run build

Authentication Notes

The web app uses NextAuth with Google and Microsoft Entra ID providers. The API validates bearer tokens and applies role policies for Parent, Child, and PlatformAdmin behavior. PlatformAdmin access is granted through API configuration allow-lists under Auth:PlatformAdmin.

Data and Persistence

• Local default provider: SQLite
• Default database file: src/LearningBank.Api/App_Data/learningbank.dev.db
• Provider selection is controlled by Database:Provider in API configuration.

Current State and Known Gaps

• Domain tests are implemented and passing.
• API test project exists, but integration test classes are not yet added.
• docker-compose.yml references Dockerfiles that are currently not present in the repository.

Contribution Guidance

1. Keep business invariants in the domain layer first.
2. Keep API endpoints thin and policy-aware.
3. Keep web client data flows through BFF route handlers.
4. Add tests with each non-trivial change.

Additional References

• Copilot project instructions: .github/copilot-instructions.md
• Design system source: DESIGN.md