Egis – Technical Journal (Day 1)

1. Project Intent & Philosophy

Egis is a private, mobile-first trading system designed around discipline, clarity, and safety.

Core principles:

Logged-in only system
Clear separation between User and Admin
Mobile-first UX
Paper trading first, real exchanges later
Architecture that allows exchange adapters to be swapped without rewriting bot logic

The system prioritizes correct structure over speed or feature volume.

2. Stack & Environment

Backend

Laravel 12
PHP 8.2
- Explicit binary:
  /RunCloud/Packages/php82rc/bin/php

Frontend

Inertia.js
React
shadcn/ui (Radix UI)
TailwindCSS
Mobile-first design

Critical Safety Rule

All automated tests MUST use SQLite
Never allow tests to touch MySQL/Postgres
phpunit.xml enforces:
- DB_CONNECTION=sqlite
- DB_DATABASE=:memory:
Add guard: tests must fail if DB is not sqlite

3. Authentication & Roles

Access Model

The system is private
All pages require authentication

Roles

There are only two roles:

Admin
Normal User

Admin Definition

Admin is defined via .env
Single admin only

Example:

[email protected]

Role Resolution

Implemented as User::isAdmin()
Simple comparison against config value
No role tables, no permissions system

4. Layout & Theming

Theme Rules

Dark theme only
Guest Layout (Login/Register) MUST visually match Authenticated Layout
No light backgrounds anywhere

Mobile-first Rules

No layout shift
No top/bottom white gaps
Numeric keyboards for numeric inputs
Buttons stacked vertically on mobile

5. Navigation & UI Separation

Strict UI Separation (Important)

User UI and Admin UI are separate component trees
No conditional JSX inside shared components

Components:

UserDashboard
AdminDashboard
UserNavigation
AdminNavigation

6. Dashboard Behavior

User Dashboard

Title:
“Hey, {user_name}”
Browser title:
“Hey, {user_name} – Egis” (only one “Egis”)

Conditional content:

If no exchange connected → show Connect Exchange
If exchange connected:
- Hide Connect Exchange
- Show Create Bot
If bots exist:
- Show Bot List
- Hide inline Create Bot
- Show Create Bot button
- Create Bot opens in modal

Admin Dashboard

Browser title:
“Admin Dashboard – Egis”
No test content
Shows:
- Total Users Count
Navigation cleaned (removed unused “Admin” gear item)

7. Exchanges System

Exchange Config (Single Source of Truth)

Defined in config, not hard-coded in UI.

Initial exchanges:

Binance
Paper

Exchange Connections

Database table supports:

user_id
exchange_key (paper, binance, …)
credentials (JSON, nullable)
status
timestamps

Paper exchange has no credentials.

8. Bots

Bot Creation

Fields:

Name
Strategy (from config)
- Initial strategy: manual
Budget (USD)

Database

bots table:

user_id
name
strategy
budget
status
- inactive (default)
- active
- issue
exchange_connection_id (nullable)

9. Bot Detail Page – Section Order

Final, enforced order:

Connect to Exchange (only if bot not connected)
Positions (if any exist)
Bot Control
Basic Information

No CSS reordering. Component structure defines order.

10. Exchange Adapter Architecture

Goal

Allow bots to switch exchanges (Paper → Binance later) without changing bot/order logic.

Core Abstraction

ExchangeAdapter interface:

getMarketPrice(symbol)

Resolver

Given a bot → returns adapter:
- paper → PaperExchangeAdapter
- binance → future adapter

11. Paper Exchange (Simulation)

Purpose

Simulate market behavior
Provide realistic fill prices
Replaceable by real exchange later

Paper Market Prices

Database:

paper_market_prices

symbol (unique)
last_price
updated_at

Behavior:

Base price from config
Small random walk per request
Price persists between requests

12. Orders & Positions (Paper Trading)

Orders

paper_orders table:

user_id
bot_id
symbol (e.g. BTCUSDT)
side (long, short)
order_type (market, limit)
size_usd
entry_price
status
filled_at
timestamps

Positions

paper_positions table:

user_id
bot_id
paper_order_id
symbol
side
status (open, closed)
size_usd
entry_price
opened_at
closed_at
exit_price
realized_pnl
timestamps

Creation is atomic (DB transaction).

13. Open Long Modal (Manual Strategy)

Modal UX

shadcn/ui Dialog
Mobile-first
No layout shift
Buttons stacked:
1. Create Order
2. Cancel

Fields

Symbol (default: BTCUSDT)
Order Type: Market / Limit
Position Size (USD)
- Numeric keyboard
Entry Price
- Only for Limit
- Hidden for Market
Notes (optional)

Behavior

Market order:
- Entry price auto-filled via PaperExchangeAdapter
Limit order:
- Entry price from user

Submission UX

Create Order button shows loading state
Disabled during submit
Modal closes on success
Success toast (overlay, no layout shift)

14. Positions Section

Display

Each position card shows:

Symbol
Side (Long/Short)
Status (Open/Closed)
Entry Price (USD formatted: $10,000.00)
Current Price (from Paper Exchange)
Unrealised PnL (USD)

Unrealised PnL Calculation

Quantity = size_usd / entry_price
Long:

(current_price – entry_price) * quantity

Short:

(entry_price – current_price) * quantity

Formatting

USD via Intl.NumberFormat
Null values shown as —

15. Delete Position (Local Only)

Rules

Delete available only in local environment
UI hidden/disabled in non-local
Backend blocks non-local deletes

Behavior

Delete position
Related order deleted too
Transactional
Confirmation dialog
UI updates immediately
Positions section disappears if empty

16. Flash Messages

Toast-style overlay
Fixed position
No layout shift
Auto-dismiss
Manual dismiss

17. Key Architectural Outcomes

Clean separation of concerns
Exchange-agnostic bot logic
Paper trading as first-class citizen
Mobile-first UX everywhere
Safe testing infrastructure
Rebuildable from config + migrations

18. Rebuild Checklist (If Needed)

If rebuilding Egis from scratch:

Set PHP 8.2 explicitly
Laravel 12 + Inertia + React + shadcn/ui
Enforce SQLite-only tests
Implement role logic via .env
Build exchange adapter layer
Implement Paper Exchange first
Build bot → order → position flow
Add PnL calculation
Lock UI to dark theme, mobile-first

End of Journal – Egis (Day 1)