AI-Powered Cryptocurrency Price Movement Prediction System
Technical Documentation & Academic Reference Manual
Version 4.2.4
Automission (ATM) is a full-stack, terminal-centric web application that delivers real-time and near-term cryptocurrency market intelligence through a command-line interface (CLI) paradigm rendered in the browser. The system integrates multi-source market data acquisition, large language model (LLM) reasoning via Google GenAI, structured prompt engineering, and a usage-metered resource economy (RPU/MRPU). It provides users with hierarchical analytical products: high-level market insights, directional coin rankings (bulls/bears), discrete long/short signals, and granular single-asset trade forecasts that include entry, stop-loss, take-profit levels, risk-reward ratios, confidence scores, and explicit risk disclosures.
Architecturally, ATM is implemented as a React 19 + TypeScript + Vite single-page application (SPA) deployed on Vercel, backed by Appwrite for authentication and document storage, and orchestrated through Zustand state management. The design prioritizes deterministic command parsing, rate-limited AI inference, transparent reasoning chains, and academic-grade output formatting using ASCII tables (cli-table3). This document constitutes a complete technical and methodological exposition intended for academic review, peer examination, and professional engineering evaluation.
- Introduction and System Overview
- Design Philosophy and Academic Motivation
- System Architecture
- Technology Stack and Dependencies
- Core Functional Modules
- Authentication and Session Management
- Resource Economy (RPU / MRPU)
- Command Interface and User Interaction Model
- Prediction Engine – Detailed Methodology
- Signal Generation Subsystem
- Forecast Engine – End-to-End Pipeline
- AI Model Integration and Prompt Engineering
- Data Sources and Feature Vectors
- Output Formatting and Presentation Layer
- State Management and Client-Side Architecture
- Security, Rate Limiting, and Error Handling
- Deployment and Operational Characteristics
- User Journeys
- Command Reference with Example Outputs and Explanations
- Quantitative Considerations and Performance Vectors
- Limitations, Assumptions, and Future Work
- Conclusion
- Illustration Diagrams
- References and Acknowledgments
Automission (ATM) is conceived as an intelligent decision-support system for cryptocurrency market participants. Unlike traditional technical analysis dashboards or black-box trading bots, ATM exposes its reasoning through a transparent, command-driven interface that mimics professional quantitative research terminals.
The primary user experience is a persistent terminal emulator. Users issue natural-language-style commands prefixed with atm, and the system responds with structured, multi-table ASCII reports that contain both quantitative metrics and qualitative AI-generated justifications.
Key value propositions:
- Multi-horizon market intelligence (macro insights → directional rankings → single-asset trade plans).
- Explicit confidence scoring and risk flag enumeration.
- Metered consumption model that encourages disciplined usage.
- Fully auditable reasoning chains generated by an LLM under controlled prompting.
- Zero-install web accessibility while preserving a professional CLI aesthetic.
The system is currently at version 4.2.4 and is deployed at https://automission.vercel.app.
The design of ATM rests on three interlocking principles drawn from quantitative finance, human-computer interaction, and machine learning systems research:
-
Transparency over opacity
Every recommendation is accompanied by a reasoning summary, detailed rationale, red-flag list, and underlying assumptions. This aligns with the growing academic and regulatory demand for explainable AI (XAI) in financial decision support. -
Hierarchical information architecture
Information is delivered in progressive layers of granularity, mirroring the classical top-down analysis workflow used by institutional research desks (macro → sector/theme → single name → trade construction). -
Resource-constrained intelligence
By introducing a finite Request Processing Unit (RPU) budget, the system forces users to treat AI inference as a scarce resource, analogous to computational budgets in high-frequency trading research environments.
These principles collectively aim to elevate the system beyond a simple chatbot into a research-grade analytical platform suitable for academic scrutiny.
The architecture follows a classic three-tier pattern adapted for a modern SPA:
- Presentation Tier: Terminal component, command parser, and response renderers.
- Application Tier: Orchestration logic under
src/x/[Private folder] that assembles multi-source context and invokes the LLM. - Data & Persistence Tier: Appwrite (authentication, user preferences, RPU counters) + external market/news APIs.
Communication between tiers is asynchronous and promise-based. All AI calls are gated by the RPU/MRPU handler before any external inference is performed.
| Category | Technology | Version / Notes | Role |
|---|---|---|---|
| Frontend Framework | React | 19.1.0 | UI & component model |
| Language | TypeScript | ~5.8.3 | Static typing throughout |
| Build Tool | Vite | 7.0.0 | Fast HMR & production bundling |
| Styling | Tailwind CSS | 4.1.11 | Utility-first styling |
| State Management | Zustand | 5.0.6 | Lightweight stores for auth, history, loading |
| Authentication & DB | Appwrite | 18.1.1 | Auth, sessions, document storage |
| LLM Provider | @google/genai | ^1.11.0 | Generative AI inference |
| Table Formatting | cli-table3 | 0.6.5 | Professional ASCII tables |
| Icons | lucide-react | 0.525.0 | UI icons |
| Routing | react-router | 7.6.3 | Client-side routes (incl. password reset) |
The project is private ("private": true) and uses ES modules ("type": "module").
Core package.json metadata:
{
"name": "automission",
"description": "AI-Powered cryptocurrency price movement prediction system.",
"author": "Firas Dabbabi <FirasDabbabi@gmail.com>.",
"version": "4.2.4",
"type": "module"
}The source tree is organized for clear separation of concerns:
src/
├── apis/ # Backend communication (Appwrite wrappers)
│ └── backend/
│ ├── auth/
│ ├── configs/
│ ├── services/predictions/
│ └── userPrefs/
├── commands/ # Pure response formatters (ASCII tables)
│ ├── details/
│ ├── feedback/
│ ├── forecasts/
│ ├── help/
│ ├── limitWarning/
│ ├── predictions/
│ │ ├── marketBears/
│ │ ├── marketBulls/
│ │ └── marketInsights/
│ ├── signals/
│ │ ├── bestLong/
│ │ └── bestShort/
│ ├── signup/
│ └── whoami/
├── components/ # Terminal UI
│ └── Terminal/
├── interfaces/ # TypeScript interfaces
├── layouts/ # Main application layout
├── stores/ # Zustand stores
│ ├── header/
│ ├── history/
│ ├── loading/
│ ├── login/
│ ├── resetNewPassword/
│ ├── resetPassword/
│ ├── signup/
│ ├── user/
│ └── userData/
├── x/ # Core intelligence engines (Private folder)
│ ├── forecasts/
│ ├── predictions/
│ │ ├── market_bears/
│ │ ├── market_bulls/
│ │ └── market_insights/
│ ├── signals/
│ │ ├── best_long/
│ │ └── best_short/
│ └── lib/
│ ├── AI/
│ │ ├── prompts/
│ │ └── AI_model.ts
│ └── RPUxMRPU_handler.ts
├── App.tsx
├── main.tsx
└── styles.css
ATM implements a complete authentication lifecycle using Appwrite:
- Session check on application mount (
checkSession()). - Persistent user data hydration.
- Dedicated routes for password reset (
/resetand/cpr).
Key session logic (excerpt from App.tsx):
useEffect(() => {
if (window.location.href.includes("reset")) {
setDisplayHelpContext(false);
}
async function sessionCheck() {
try {
const response = await checkSession();
setUserId(response && typeof response.userId === "string" ? response.userId : null);
areRPUandMRPUEqual();
setIsLoggedin(true);
} catch (error) {
console.error("Error checking session:", error);
setIsLoggedin(false);
}
}
sessionCheck();
}, []);Login Journey
Signup Journey
Password Reset Journey
Session state is held in Zustand stores (useUser, useUserData) and is synchronized with Appwrite on every critical action.
A distinctive engineering feature is the dual-counter resource system:
- RPU (Request Processing Units) – current consumption counter.
- MRPU (Maximum Request Processing Units) – hard limit per user.
Before any AI-powered command executes, the system invokes the following handler:
export async function PRUxMRPU_handler(incrementValue?: number) {
const { setUpdateUserData, updateUserData } = useUserData.getState();
try {
const res = await areRPUandMRPUEqual();
if (res === 'not equal') {
// Await the incrementRPU call directly
const incRes = await incrementRPU(incrementValue);
if (incRes === true) {
setUpdateUserData(!updateUserData);
return true;
}
} else if (res === 'equal') {
return 'limitWarning';
} else {
console.error('Unexpected result when comparing RPU and MRPU:', res);
return undefined;
}
} catch (error) {
console.error('Error occurred during RPU check/increment:', error);
return undefined;
}
}Most prediction and signal commands cost 5 RPU. When RPU reaches MRPU, the system returns a limit-warning response and refuses further inference. This mechanism serves both as a cost-control layer for the LLM provider and as a pedagogical device that teaches users the scarcity of high-quality AI analysis.
Commands follow a consistent grammar:
atm <verb> [sub-command] [arguments]
| Command | Description |
|---|---|
atm help |
Show this help message |
atm clear |
Clear the terminal |
atm login |
Log into your account |
atm signup |
Create a new user account |
atm reset p |
Reset your account password |
atm whitepaper |
Learn more about this project |
| Category | Command | Cost | Description |
|---|---|---|---|
| General | atm help |
0 | Full help message |
atm clear |
0 | Clear the terminal | |
| Account | atm logout |
0 | Sign out of the current session |
atm whoami |
0 | Display current username and email | |
atm details |
0 | Display your account details | |
| Resources | atm whitepaper |
0 | Learn more about this project |
atm feedback |
0 | Share your thoughts or report issues | |
| Predictions | atm predict insights |
5 | Access high-level crypto market overviews with future forecasts |
atm predict bulls |
5 | Highlight coins projected to see the strongest gains in value | |
atm predict bears |
5 | Reveal assets anticipated to face the steepest declines in value | |
| Signals | atm best long |
5 | Uncover top coin positioned for strong upward momentum |
atm best short |
5 | Reveal the asset most vulnerable to sharp decline | |
| Forecasts | atm forecast <COIN> |
5 | Predicts the future price direction and trend for a specific cryptocurrency |
Note: Some commands deduct points from your RPU per request.
The prediction subsystem (src/x/predictions/) produces three complementary views.
The
x/directory contains proprietary algorithmic logic and supporting implementation details that I have chosen to keep private. To protect intellectual property and ensure responsible disclosure, this directory and its associated technical context are intentionally excluded from the public repository and this documentation.The publicly available materials are intended to demonstrate the system's architecture, engineering approach, and overall functionality without disclosing the underlying private implementation.
Thank you for your understanding and respect for this decision.
Returns a comprehensive macro snapshot containing:
- Total market capitalization and 24 h volume
- BTC dominance
- Sentiment score (0–100) and classification
- Overall trend and dominance influence
- Current market direction with justification
- Signal strength evaluation
Response formatter excerpt:
function command_response_atm_predict_insights(data: {
date: string;
market_cap_usd: number;
volume_usd: number;
btc_dominance: number;
sentiment_score: number;
sentiment_classification: string;
bitcoin_price_USD: number;
previous_bitcoin_price_USD: number;
active_cryptocurrencies: number;
active_markets: number;
trend_overall_market_trend: string;
trend_dominance_influence: string;
market_direction_current_direction: string;
market_direction_justification: string;
signal_strength_strength_evaluation: number;
signal_strength_classification: string;
}) {
const header = `
╔══════════════════════════════════════════════╗
║ MARKET INSIGHTS REPORT ║
║ [${data.date}] ║
╚══════════════════════════════════════════════╝
`;
// ... table construction with cli-table3
}These modules identify the coins with the strongest projected positive or negative price trajectories. They combine technical momentum, sentiment, and news-derived fundamental context.
The signal layer (atm best long / atm best short) narrows the field to a single highest-conviction opportunity. The response formatter produces:
- A ranked table containing coin name, symbol, market sentiment, reasoning, and signal strength.
- An instructional tip encouraging the user to run the deeper
atm forecastcommand on the recommended asset.
Best Long response structure (excerpt):
function command_response_atm_best_long(
bestLong:
| { coin: string; symbol: string; market_sentiment: string; reasoning: string; signal_strength: string }
| { coin: string; symbol: string; market_sentiment: string; reasoning: string; signal_strength: string }[]
) {
const data = Array.isArray(bestLong) ? bestLong : [bestLong];
const header = `
╔════════════════════════════════════════════════╗
║ BEST LONG POSITION RECOMMENDATION — ${new Date().toISOString().split('T')[0]} ║
╚════════════════════════════════════════════════╝
`;
// Primary table + forecast tip table
}This progressive disclosure design encourages users to escalate from broad signal to detailed trade construction only when conviction is high.
The most sophisticated component is the single-asset forecast pipeline (runForecastCoin).
-
News Acquisition
Parallel fetches from NewsAPI for the queries “crypto”, “cryptocurrencies”, and “bitcoin”. Articles are reduced to{title, description}pairs. -
Macro Context
Invocation ofrunMarketInsights()to obtain the current global market state vector. -
Asset-Specific Insights
Call tocoinInsights(coin)that retrieves technical and fundamental descriptors for the target asset. -
Prompt Assembly
All three data sources are injected into a carefully engineered prompt template (GET_forecast_prompt). -
LLM Inference
The assembled prompt is sent to the Google GenAI model viaAI_model(). The response is cleaned of markdown fences and parsed as JSON. -
Structured Output
The resulting object conforms to theForecastinterface and is rendered into seven distinct ASCII tables.
interface ExpectedDuration {
value: number;
unit: string;
}
interface Recommendations {
order_type: string;
leverage_suggested: number;
notes: string;
}
interface Meta {
timestamp_utc: string;
model_version: string;
}
export interface Forecast {
coin_name: string;
coin_symbol: string;
trade_type: 'long' | 'short';
entry_price: number;
stop_loss_price: number;
stop_loss_distance_pct: number;
take_profit_price: number;
take_profit_distance_pct: number;
risk_reward_ratio: number;
expected_duration: ExpectedDuration;
confidence_score: number;
signal_strength: string;
reasoning_summary: string;
detailed_rationale: string;
red_flags: string[];
assumptions: string[];
recommendations: Recommendations;
meta: Meta;
}async function runForecastCoin(coin: string) {
// STEP 1: GET GLOBAL NEWS (fundamentals)
async function fetchNews(query: string) {
const apiKey = import.meta.env.VITE_NEWS_API_KEY;
const url = `https://corsproxy.io/?https://newsapi.org/v2/everything?q=${encodeURIComponent(query)}&language=en&pageSize=50&apiKey=${apiKey}`;
// ... fetch and map to {title, description}
}
async function getAllNews() {
const [crypto, cryptocurrencies, bitcoin] = await Promise.all([
fetchNews("crypto"),
fetchNews("cryptocurrencies"),
fetchNews("bitcoin"),
]);
return [...crypto, ...cryptocurrencies, ...bitcoin];
}
const todaysMarketNews = await getAllNews();
// STEP 2: GET MARKET INSIGHTS (fundamentals)
const marketInsights = await runMarketInsights();
// STEP 3: GET THE REQUESTED COIN INSIGHTS (technical)
const requestedCoinInsights = await coinInsights(coin);
// STEP 4: MERGE & PASS RESULTS OF STEP [1,2,3] TO BE AI-ANALYZED
const merged_prompt_with_fetched_data = GET_forecast_prompt({
todaysMarketNews,
marketInsights: marketInsights as MarketInsights,
requestedCoinInsights
});
// STEP 5: Send the collected data to AI model
const AI_response = await AI_model(merged_prompt_with_fetched_data);
const cleanJson = AI_response?.replace(/^```json\n/, '').replace(/\n```$/, '');
const data = JSON.parse(cleanJson ? cleanJson : "{}");
return data;
}This schema enforces a minimum information set that any responsible trading recommendation should contain: entry, risk parameters, reward parameters, time horizon, confidence, and explicit risk disclosure.
The LLM client resides in src/x/lib/AI/AI_model.ts. Prompts are versioned and stored under src/x/lib/AI/prompts/.
Prompt engineering follows best practices:
- Clear role assignment (“You are a quantitative crypto research analyst…”).
- Explicit output schema (JSON-only).
- Injection of raw market data, news headlines, and technical metrics as context.
- Instruction to enumerate red flags and assumptions.
- Temperature and sampling parameters controlled at the model call site.
The system deliberately forces the model to produce machine-parseable JSON rather than free-form prose, enabling reliable downstream formatting and future programmatic consumption.
| Source | Data Type | Usage |
|---|---|---|
| NewsAPI | Headlines + descriptions | Fundamental / sentiment context |
| Market Insights API | Cap, volume, dominance, sentiment | Macro state vector |
| Coin Insights | Price, technical indicators, etc. | Asset-specific features |
| Appwrite | User profile, RPU counters | Authorization & metering |
Feature vectors are currently assembled as unstructured text within the prompt. Future iterations may introduce explicit numerical embeddings or vector databases for retrieval-augmented generation (RAG).
All analytical responses are generated by pure functions under src/commands/ that consume typed data and return strings. The library cli-table3 is used with custom border characters to produce publication-quality ASCII tables that remain legible in both dark and light terminal themes.
Example header style:
╔═════════════════════════════════════╗
║ TRADE RECOMMENDATION — 2026-10-14 ║
╚═════════════════════════════════════╝
This design choice ensures that outputs can be copied into research notes, emails, or academic appendices without loss of structure.
Forecast response construction (excerpt):
export default function command_response_atm_forecast_coin(forecast: Forecast): string {
// 1. Overview table
// 2. Trade details table (Entry, SL, TP, RR, Duration)
// 3. Reasoning summary
// 4. Detailed rationale
// 5. Red flags / risks
// 6. Underlying assumptions
// 7. Execution recommendations (order type, leverage, notes)
return [
header,
overviewTable.toString(),
tradeTable.toString(),
summaryTable.toString(),
rationaleTable.toString(),
redFlagTable.toString(),
assumptionTable.toString(),
recommendationTable.toString(),
].join('\n');
}Zustand stores are narrowly scoped:
| Store | Responsibility |
|---|---|
useUser |
Authentication status and user ID |
useUserData |
Profile and RPU metrics |
useHistory |
Terminal command history |
useLoading |
Global loading indicators |
| Auth flow stores | Multi-step signup / reset password flows |
This modular store design prevents unnecessary re-renders and keeps the terminal responsive even during long-running AI inferences.
- All sensitive operations require an active Appwrite session.
- RPU gating prevents unbounded LLM cost exposure.
- Network errors in news or market data fetches degrade gracefully (empty arrays are substituted).
- JSON parsing of LLM responses is protected with fallback empty objects.
- Password reset flows use dedicated, short-lived routes.
- Hosted on Vercel with automatic preview deployments.
- Environment variables manage API keys (NewsAPI, Google GenAI, Appwrite).
- Build pipeline:
tsc -b && vite build. - Version is injected into the document title:
Automission (ATM) CLI v${VITE_VERSION_MAJOR}.
Live deployment: https://automission.vercel.app
Guest Terminal
Description: Initial unauthenticated state showing the welcome banner and available guest commands.
Successful Login
Description: Transition afteratm loginwith updated prompt reflecting authenticated status.
RPU Exhaustion
Description: Display of the limit-warning message when RPU equals MRPU.
Multi-Predections Output
Description: Multi-table forecasts.
Best Short Signal
Description: Example of the best-short recommendation table plus the follow-up forecast tip.
Purpose: Provide a dated macro snapshot of the cryptocurrency market.
Cost: 5 RPU
Key metrics returned:
- Market capitalization and volume (absolute USD figures)
- BTC dominance percentage
- Sentiment score ∈ [0, 100]
- Qualitative trend and direction statements
- Numeric signal strength evaluation
Interpretation guidance:
A sentiment score > 65 combined with a “Strong” signal classification typically indicates a constructive macro environment for long-biased strategies. Conversely, scores < 35 with negative classification favor caution or short bias.
Purpose: Surface the single highest-conviction directional opportunity.
Output structure:
- Ranked table (usually a single row).
- Instructional tip linking to the deeper forecast command.
Academic note: This command implements a form of “best-idea” concentration, a well-documented phenomenon in active portfolio management research.
Purpose: Generate a complete, risk-managed trade plan.
Quantitative outputs of primary interest:
| Field | Description | Typical Range / Notes |
|---|---|---|
risk_reward_ratio |
Reward-to-risk ratio | Preferably ≥ 1.5 |
confidence_score |
Continuous self-assessed confidence | [0, 1] |
stop_loss_distance_pct |
Distance from entry to stop-loss | Percentage |
take_profit_distance_pct |
Distance from entry to take-profit | Percentage |
expected_duration |
Estimated holding period | Value + unit (e.g., 4–7 days) |
Example interpretation (hypothetical):
Entry $62,450 · SL $60,100 (−3.76 %) · TP $68,200 (+9.21 %) · RR 2.45 · Confidence 0.78 · Duration 4–7 days.
Such a profile would be considered a high-quality intermediate-term long setup under conventional risk-management frameworks.
While live performance statistics are outside the scope of this documentation (the system is a decision-support tool rather than an automated trading engine), several quantitative design decisions merit explicit statement:
- Confidence scores are produced by the LLM under instruction to self-assess; they are not calibrated probabilities from a supervised model.
- Risk-reward ratios are computed deterministically from the three price levels returned by the model.
- Position sizing is deliberately left to the user; the system only suggests leverage and order type.
- All monetary figures are expressed in USD; percentage distances are calculated relative to the recommended entry.
Future academic extensions could include:
- Back-testing of historical forecasts against realized price paths.
- Calibration of confidence scores against empirical hit rates.
- Integration of realized volatility surfaces for dynamic position sizing.
- Dependence on third-party news and market data APIs (availability and rate limits).
- LLM non-determinism (identical prompts may yield slightly different rationales).
- Absence of real-time order-book or on-chain flow data.
- No automated execution or brokerage connectivity.
- Market data and news feeds are timely and approximately accurate.
- The LLM has been sufficiently instruction-tuned to respect the requested JSON schema.
- Users possess the domain knowledge to interpret risk parameters and size positions appropriately.
- Vector-store retrieval of historical analogous market regimes.
- Multi-model ensemble voting for higher robustness.
- User-configurable risk templates and position-size calculators.
- Export of forecasts to structured formats (CSV, JSON, PDF).
Automission (ATM) represents a deliberate synthesis of modern large-language-model capabilities, classical quantitative research workflows, and thoughtful human-computer interaction design. By presenting AI-generated market intelligence inside a professional terminal interface, enforcing resource scarcity, and insisting on structured, risk-aware outputs, the system elevates conversational AI from a novelty into a research-grade analytical instrument.
The architecture is modular, the code is typed, the outputs are transparent, and the resource economy is explicit. These characteristics make ATM suitable both for practical decision support and for academic examination of human-AI collaboration in financial domains.
Forecast Pipeline Sequence
RPU State Machine
Data Flow for Multi-Source Context Assembly
- Appwrite Documentation – Authentication & Database
- Google Generative AI SDK
- NewsAPI
- React, Vite, Zustand, Tailwind CSS, TypeScript, cli-table3 official documentation
- Academic literature on Explainable AI in finance and hierarchical decision-support systems
Author
Firas Dabbabi
GitHub: https://github.com/fifolio
LinkedIn: https://linkedin.com/in/fifolio
Repository
https://github.com/fifolio/ATM
Live Application
https://automission.vercel.app
End of Documentation
Document prepared for academic and professional review – October 2026