---
## 🏗️ Architecture Overview
OpenStock leverages a resilient event-driven architecture powered by **Inngest**. We prioritize uptime for our generative features by utilizing a multi-provider AI strategy.
### 🧠 Intelligent Model Routing
We don't rely on a single point of failure. Our AI infrastructure automatically routes around outages.
```mermaid
graph LR
A[User Action / Cron] -->|Trigger| B(Inngest Function);
B --> C{Primary Provider};
C -->|Gemini 2.5 Flash Lite| D[Generate Content];
C -.->|Error / Rate Limit| E{Fallback Provider};
E -->|Siray.ai Ultra| D;
D --> F[Email / Notification];
style C fill:#20c997,stroke:#333,stroke-width:2px,color:black
style E fill:#3b82f6,stroke:#333,stroke-width:2px,color:white
style D fill:#fff,stroke:#333,stroke-width:2px,color:black
```
---
## 🤝 AI Partners
### Primary: Google Gemini
The workhorse of our generative content. Fast, efficient, and deeply integrated via Inngest.
### Fallback: Siray.ai
> [!IMPORTANT]
> **Zero Downtime Guarantee.**
> When Gemini wavers, **Siray.ai** takes over instantly. No user request is ever dropped.
The robust infrastructure backing OpenStock.
---
## ⚡ Serverless Functions (Inngest)
Our background jobs are defined in `lib/inngest/functions.ts`.
| ID | Type | Schedule/Trigger | Purpose |
| :--- | :--- | :--- | :--- |
| `sign-up-email` | 🔔 Event | `app/user.created` | **Personalized Onboarding.** Generates a custom welcome message based on user quiz results. |
| `weekly-news-summary` | ⏱️ Cron | `0 9 * * 1` (Mon 9AM) | **Market Intelligence.** Summarizes top financial news and broadcasts to all users via Kit. |
| `check-stock-alerts` | ⏱️ Cron | `*/5 * * * *` | **Real-time Monitoring.** Checks user price targets against live market data. |
| `check-inactive-users` | ⏱️ Cron | `0 10 * * *` | **Re-engagement.** Identifies dormant users (>30 days) and sends a "We miss you" nudge. |
---
## 🔌 API Integrations
📈 Stock Data: Finnhub
* **Base URL:** `https://finnhub.io/api/v1`
* **Key Features:** Real-time quotes, technical indicators, market news.
* **Auth:** `NEXT_PUBLIC_FINNHUB_API_KEY`
📧 Email & Marketing: Kit (ConvertKit)
* **Role:** High-volume user broadcasts and tag management.
* **Key Endpoints:**
* `POST /v3/tags/{tag_id}/subscribe` (User Migration)
* `POST /v3/broadcasts` (Newsletters)
* **Auth:** `KIT_API_KEY` • `KIT_API_SECRET`
🗄️ Database: MongoDB Atlas
* **Connection:** Standard URI (DNS SRV bypassed for maximum reliability).
* **Collections:** `users`, `watchlists`, `alerts`.
---
Documentation © Open Dev Society. Built with ❤️ for the Open Source Community.
