88 lines
4.1 KiB
Markdown
88 lines
4.1 KiB
Markdown
# Project Structure
|
|
|
|
## Backend Architecture
|
|
|
|
```
|
|
app/
|
|
├── main.py # FastAPI app, lifespan, router registration
|
|
├── config.py # Pydantic settings from .env
|
|
├── database.py # Async SQLAlchemy engine + session factory
|
|
├── dependencies.py # DI: DB session, auth guards (require_access, require_admin)
|
|
├── exceptions.py # Custom exception hierarchy (ValidationError, NotFoundError, etc.)
|
|
├── middleware.py # Global error handler → JSON envelope
|
|
├── cache.py # LRU cache with per-ticker invalidation
|
|
├── scheduler.py # APScheduler job definitions
|
|
├── models/ # SQLAlchemy ORM models
|
|
├── schemas/ # Pydantic request/response schemas
|
|
├── services/ # Business logic layer
|
|
├── providers/ # External data provider integrations
|
|
└── routers/ # FastAPI route handlers
|
|
```
|
|
|
|
## Frontend Architecture
|
|
|
|
```
|
|
frontend/src/
|
|
├── App.tsx # Route definitions
|
|
├── main.tsx # React entry point
|
|
├── api/ # Axios API client modules (one per resource)
|
|
├── components/
|
|
│ ├── admin/ # User table, job controls, settings, data cleanup
|
|
│ ├── auth/ # Protected route wrapper
|
|
│ ├── charts/ # Canvas candlestick chart
|
|
│ ├── layout/ # App shell, sidebar, mobile nav
|
|
│ ├── rankings/ # Rankings table, weights form
|
|
│ ├── scanner/ # Trade table
|
|
│ ├── ticker/ # Sentiment panel, fundamentals, indicators, S/R overlay
|
|
│ ├── ui/ # Badge, toast, skeleton, score card, confirm dialog
|
|
│ └── watchlist/ # Watchlist table, add ticker form
|
|
├── hooks/ # React Query hooks (one per resource)
|
|
├── lib/ # Types, formatting utilities
|
|
├── pages/ # Page components (Login, Register, Watchlist, Ticker, Scanner, Rankings, Admin)
|
|
├── stores/ # Zustand auth store
|
|
└── styles/ # Global CSS with glassmorphism classes
|
|
```
|
|
|
|
## Key Patterns
|
|
|
|
### Backend
|
|
|
|
- **Layered architecture**: Router → Service → Model
|
|
- **Dependency injection**: FastAPI Depends() for DB session and auth
|
|
- **Exception handling**: Custom exceptions caught by global middleware, returned as JSON envelope
|
|
- **API envelope**: All responses wrapped in `{ status: "success"|"error", data: any, error?: string }`
|
|
- **Cascade deletes**: Ticker deletion cascades to all related data (OHLCV, sentiment, fundamentals, S/R, scores, trades, watchlist)
|
|
- **Async everywhere**: All DB operations use async/await with asyncpg
|
|
|
|
### Frontend
|
|
|
|
- **API client**: Axios interceptors for JWT injection and envelope unwrapping
|
|
- **Server state**: TanStack React Query with query keys per resource
|
|
- **Client state**: Zustand for auth (token, user, login/logout)
|
|
- **Error handling**: ApiError class, toast notifications for mutations
|
|
- **Protected routes**: ProtectedRoute wrapper checks auth, redirects to /login
|
|
- **Glassmorphism**: Frosted glass panels, gradient text, ambient glow, mesh gradient background
|
|
|
|
## Database Models
|
|
|
|
All models inherit from `Base` (SQLAlchemy declarative base):
|
|
|
|
- `Ticker`: Registry of tracked symbols (cascade delete parent)
|
|
- `OHLCVRecord`: Price data (open, high, low, close, volume)
|
|
- `SentimentScore`: Sentiment analysis results with time-decay
|
|
- `FundamentalData`: P/E, revenue growth, earnings surprise, market cap
|
|
- `SRLevel`: Support/Resistance levels with strength scoring
|
|
- `DimensionScore`: Individual dimension scores (technical, sr_quality, sentiment, fundamental, momentum)
|
|
- `CompositeScore`: Weighted composite score
|
|
- `TradeSetup`: Detected R:R setups (long/short, entry, stop, target)
|
|
- `WatchlistEntry`: User watchlist entries (auto/manual)
|
|
- `User`: Auth and access control
|
|
- `Settings`: System-wide configuration
|
|
|
|
## Testing
|
|
|
|
- Backend tests: `tests/unit/` and `tests/property/`
|
|
- Frontend tests: `frontend/src/**/*.test.tsx`
|
|
- Fixtures in `tests/conftest.py`
|
|
- Hypothesis strategies for property-based testing
|