Portfolio Service
Purpose
Investment portfolio management — holdings, orders, positions, and P&L tracking.
Responsibilities
- Portfolio CRUD
- Holdings and positions
- Order management
- Cost basis tracking
- P&L calculation (realized/unrealized)
Non-Responsibilities
- Market prices (Market Data Service)
- Trade execution (external)
- Analytics aggregation (Analytics Service)
APIs
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/v1/portfolios | Bearer | Create portfolio |
| GET | /api/v1/portfolios/{id} | Bearer | Get portfolio |
| GET | /api/v1/portfolios/{id}/holdings | Bearer | List holdings |
| POST | /api/v1/portfolios/{id}/orders | Bearer | Place order |
| GET | /api/v1/portfolios/{id}/pnl | Bearer | P&L summary |
Database
| Table | Key Columns | Description |
|---|---|---|
| portfolios | id, customer_id, name, currency | Portfolio records |
| holdings | id, portfolio_id, security_id, quantity, cost_basis | Positions |
| orders | id, portfolio_id, security_id, side, quantity, status | Orders |
| pnl_snapshots | portfolio_id, realized, unrealized, date | Daily P&L |
Kafka
Produces: PortfolioUpdated, OrderPlaced, OrderFilled
Consumes: MarketPriceUpdated
Dependencies
Sync: Market Data Service Async: Price updates via Kafka
Failure Handling
- Stale prices → flag holdings with last_price_date
- Order rejection → status update + notification
Scaling
Moderate traffic. Cache market prices in Redis.
Security
Customers access own portfolios. PORTFOLIO_MANAGER for managed portfolios.
Observability
Metrics: portfolio_orders_total, pnl_calculation_duration.