Skip to content

Add product docs and landing page with / and /terminal routing #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HamzaAhmad6292 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add product docs and landing page with / and /terminal routing #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 121 additions & 0 deletions ARCHITECTURE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,121 @@
# BlockForecast — Architecture

**Repo:** Everything runs from this single repository. There is **no other repo** for this app.

**Make.com:** We expose an HTTP webhook that **Make.com** (or any automation tool) can call to push token data into BlockForecast. Make.com is not part of this repo—it’s an optional external service that sends POST requests to our server. If you don’t use Make.com, the app still works (tokens come from Birdeye + our scanner).

---

## High-level architecture

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│ BROWSER │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐ │
│ │ React (Vite) │ │ Phantom │ │ DexScreener │ │ Google Gemini (AI) │ │
│ │ Frontend │ │ Wallet │ │ (iframe │ │ (client-side analyze │ │
│ │ │ │ inject │ │ chart) │ │ + TTS voice alerts) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────────┬─────────────┘ │
│ │ │ │ │ │
│ │ HTTP/WS │ sign tx │ embed only │ API key │
└─────────┼─────────────────┼─────────────────┼─────────────────────┼───────────────┘
│ │ │ │
▼ │ │ ▼
┌──────────────────────────┴──────────────────────────────────────────────────────┐
│ BLOCKFORECAST SERVER (Node.js / Express) │
│ ┌─────────────────────────────────────────────────────────────────────────────┐ │
│ │ REST API │ WebSocket │ Auth │ Risk engine │ Static (Vite/dist) │ │
│ └─────────────────────────────────────────────────────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ SQLite │ │ broadcast │ │ Gemini API │ │
│ │ blockforecast│ │ TOKEN_UPDATE│ │ (server AI │ │
│ │ .db │ │ to clients │ │ analyze) │ │
│ └─────────────┘ └─────────────┘ └──────┬──────┘ │
└─────────────────────────────────────────────────────────────┼────────────────────┘
│
┌────────────────────────────────────────────────────┼────────────────────┐
│ EXTERNAL SERVICES │ │
▼ ▼ ▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Birdeye │ │ Bitquery │ │ Helius RPC │ │ Google Gemini │ │ Make.com │
│ new_listing + │ │ GraphQL │ │ (or Solana │ │ (AI analysis │ │ (optional) │
│ price API │ │ Pump.fun bonding│ │ public RPC) │ │ server-side) │ │ POST webhook │
│ │ │ transfers │ │ wallet balance │ │ │ │ /api/webhook/ │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ make → server │
└─────────────────┘
```

---

## Mermaid diagram (for docs / Confluence / GitHub)

Use this in any tool that renders Mermaid (e.g. GitHub, GitLab, Notion, Confluence).

```mermaid
flowchart TB
subgraph Browser["Browser"]
FE[React Frontend\nVite]
Phantom[Phantom Wallet]
DexEmbed[DexScreener\niframe chart]
GeminiClient[Gemini client\nanalyze + TTS]
end

subgraph BlockForecast["BlockForecast Server (Node.js)"]
API[REST API]
WS[WebSocket]
Auth[Auth]
Engine[Risk scoring engine]
Static[Static / Vite]
DB[(SQLite\nblockforecast.db)]
GeminiServer[Gemini API\nserver-side AI]
end

subgraph External["External services"]
Birdeye[Birdeye\nnew_listing + price]
Bitquery[Bitquery\nPump.fun + transfers]
Helius[Helius RPC\nor Solana RPC]
GeminiAPI[Google Gemini]
Make[Make.com\noptional webhook]
end

FE -->|HTTP / WS| API
FE -->|HTTP / WS| WS
Phantom -->|sign tx| FE
DexEmbed -->|embed only| FE
GeminiClient -->|API key| GeminiAPI

API --> DB
API --> Auth
Engine --> DB
WS -->|TOKEN_UPDATE| FE
API --> GeminiServer
GeminiServer --> GeminiAPI

BlockForecast -->|new listings, price| Birdeye
BlockForecast -->|bonding, transfers| Bitquery
BlockForecast -->|balance, RPC| Helius
Make -->|POST token payload| API
```

---

## Data flow (short)

| Flow | Description |
|------|-------------|
| **Token pipeline** | Server calls Birdeye (new listings) + Bitquery (bonding, transfers) → runs risk engine → writes to SQLite → broadcasts `TOKEN_UPDATE` over WebSocket. Frontend gets feed via REST and live updates via WS. |
| **Make.com (optional)** | A Make.com scenario (or any HTTP client) POSTs a token payload to `POST /api/webhook/make`. Server merges with DB, runs risk engine, upserts token, broadcasts. No other repo; Make.com is external. |
| **Ingest** | Same as Make.com but generic: `POST /api/ingest` for internal or other tools to push token data. |
| **Auth** | Password hash in SQLite `config` table. (MVP will add wallet connect + password.) |
| **AI** | Server: `GET /api/ai/analyze/:mint` uses Gemini. Client: `gemini.ts` can call Gemini for richer analyze + voice alerts. |
| **Charts** | Frontend embeds DexScreener iframe (no backend call). |

---

## Summary

- **One repo:** This BlockForecast repo. No other repo for this app.
- **Make.com:** Optional. It’s an external automation service that can POST to our webhook (`/api/webhook/make`) to push token data in. We don’t host or clone Make.com.
- **External APIs we use:** Birdeye, Bitquery, Helius (or public Solana RPC), Google Gemini. DexScreener is embed-only in the frontend.
Loading