How amitesh007z/stella works
Project type and purpose
• Stella Protocol is a full-stack web application providing a routing intelligence engine for the Stellar network.
• The frontend is built with React (Vite), the backend with Fastify (Node.js), and it uses SQLite (WAL) for persistence.
• Key capabilities include anchor discovery, asset registry, in-memory route graph construction, pathfinding, quote generation, and execution planning.
File structure
• Monorepo root with two top-level folders:
• frontend/ – React code, pages, components, API client
• backend/ – Fastify server, configuration, database migrations, services, routes
• backend/src/services/ subdivides core domains: anchor crawler, asset registry, graph builder, route engine, execution engine
• Configuration files: .env examples, vercel.json, vite.config.js, DEPLOY.md
• README.md documents architecture, API, tech stack
README for architecture insights
• Core services listed: Anchor Crawler, Asset Registry, Route Graph, Route Resolver, Execution Engine, Quote Manager
• External dependencies: Horizon Testnet API, stellar.toml crawl, Freighter wallet
a. Main components (from top to bottom)
• User Interface (Browser/React SPA)
• API Layer (Fastify HTTP server)
• Core Services (vertically stacked):
1. Anchor Crawler
2. Asset Registry
3. Route Graph Builder
4. Route Discovery Engine (Pathfinder → Resolver → Cache)
5. Execution Engine (FeeCalc → Slippage → Planner → QuoteManager)
• Persistence & Cache: SQLite (WAL mode) + In-memory LRU cache
• External Systems: Stellar Horizon API, stellar.toml sources, Freighter Wallet
b. Relationships & interactions
• UI → REST API calls (/api/routes, /api/graph, /api/anchors, /api/quotes)
• API Layer delegates to Core Services, which read/write to SQLite or in-memory cache
• Anchor Crawler fetches stellar.toml (HTTP) and populates Asset Registry
• Graph Builder polls Asset Registry and Horizon for orderbook data to build weighted graph
• Route Discovery queries graph, applies algorithms, then Horizon validation
• Execution Engine uses Horizon SDK and Freighter to prepare transactions
c. Architectural patterns & design principles
• Layered architecture (presentation → API → domain services → data)
• Modular services (single responsibility for crawling, indexing, routing, execution)
• Two-layer cache: fast in-memory LRU + durable SQLite TTL cache
• Clean separation of concerns: routes vs. services vs. lib vs. plugins
• Graceful shutdown and health checks for reliability
d. Key technologies & libraries
• Frontend: React 19, Vite, React Router, Freighter API
• Backend: Node.js 20+, Fastify 5, better-sqlite3, @stellar/stellar-sdk, Pino
• Deployment: Vercel (frontend), Railway/Vercel (backend)
Detail without over-fragmentation
• Every major service from the file structure
• How migrations and config fit into the startup sequence (e.g., Fastify app init → migrate.js → service scheduling)
• “vertical” nature by ordering from top (user) down to bottom (network/deployment targets)