🚀 InventoryAlert Documentation (v1)
Welcome to the InventoryAlert System Wiki — the single source of truth for architecture, operational runbooks, and API contracts.
InventoryAlert is a real-time stock portfolio and alerting ecosystem built on .NET 10 and Next.js 15 (App Router). It tracks global stock prices via Finnhub, evaluates user-defined Alert Rules, and delivers in-app notifications when thresholds are crossed.
v2 Note: The system has been fully refactored from an inventory-management domain to a finance-domain vocabulary.
Product→StockListing,StockTransaction→Trade, Telegram → In-App Notifications.
🧭 Navigating the Wiki
🌟 Project & Architecture
Understand the "why" and the overall shape of the system.
- Project Introduction — Core features, capabilities, and seed accounts.
- Architecture Overview — System diagram, tech stack, Docker service map.
- Domain & Structure — Clean Architecture layers, solution folder layout, placement rules.
- Microservice Components — Runtime interaction between API, Worker, Redis, SQS, Finnhub.
💾 Core Logic & Flows
Deep dive into the data rules and execution sequences.
- Data Model — PostgreSQL ER diagram, DynamoDB tables, AlertCondition enum.
- Caching Strategy — Redis key namespaces, TTLs, and rate limit guard.
- User Authentication — JWT lifecycle, refresh rotation, claim structure.
- Price Sync Flow — End-to-end price fetch → PriceHistory → alert evaluation → notification.
- Alert Dispatch — AlertRule evaluation, Redis cooldown, SQS relay.
- Business Logic — Trade ledger semantics, symbol discovery, cascade delete rules, validation.
🔌 APIs & Jobs
How the system talks to the outside world and background workloads.
- Internal API Reference — All v1 endpoints: Auth, Portfolio, Stocks, Market, Watchlist, AlertRules, Notifications, Events.
- Event Handling — SQS topology, event type strings, deduplication pattern.
- External Integrations — Finnhub, SQS, DynamoDB, Redis integration details.
- Background Workers — All 8 background jobs (7 recurring + 1 continuous) with cron schedules and Finnhub endpoints.
- Hangfire Monitoring — Dashboard guide, job catalog, failure impact.
🛠️ Developer Guide
Everything you need to run, build, and maintain the platform.
- Getting Started — Docker commands, seed credentials, service URLs.
- .NET CLI Reference — Migrations, test commands, publish guide.
- Testing & Standards — C# 12 rules, primary constructors, and common patterns.
- Test Structure & App Quality — Test project architecture, CI/CD gates, and runtime observability.
- Integration Testing Tiers — Deep dive into White-box, Black-box, and Whole-Flow tests.
- Operational Runbook — Troubleshooting guide, DB queries, common debug scenarios.
- AI Agent Workflows — Slash commands, transaction capture patterns, file placement rules.
🖥️ Front-End
- UI Architecture — App Router layout, page → API map, component library, state management.
- Feature Breakdown — All user-facing pages, notification hub flow, symbol discovery UX.
💡 Tip: Use the sidebar search to instantly jump to specific API paths, entity names, or architecture diagrams.