-
Notifications
You must be signed in to change notification settings - Fork 0
Home
SAGE Documentation Bot edited this page Jan 5, 2026
·
16 revisions
Single Source of Truth for all Sage.ai project documentation
This repository contains all authoritative documentation, specifications, and architecture guidelines for the Sage.ai platform - an AI-powered investment mentor that helps users make smarter financial decisions.
Sage.ai is organized across 4 independent repositories:
- Purpose: Documentation and specifications
- Repository: https://github.com/5010-dev/sage-docs
- Role: Single Source of Truth for all specs and architecture docs
- Purpose: React web application
- Repository: https://github.com/5010-dev/sage-front
- Tech Stack: React 18.3, Vite 5, TypeScript, Zustand, TanStack Query
-
Deployment: AWS Amplify (automatic on push to
main)
- Purpose: Nest.js API server
- Repository: https://github.com/5010-dev/sage-back (to be created)
- Tech Stack: Nest.js 10.x, Prisma 5.x, PostgreSQL 18, Valkey 8.x
- Deployment: AWS ECS Fargate via GitHub Actions
- Purpose: Infrastructure as Code (Pulumi)
- Repository: https://github.com/5010-dev/sage-infra (to be created)
- Tech Stack: Pulumi 3.x (TypeScript)
- Resources: ECS, RDS, ElastiCache, ALB, Amplify
sage-docs/
├── specs/ # Technical specifications (AUTHORITATIVE)
│ ├── backend-spec.md # Backend API, Agent Pipeline, SSE streaming
│ ├── frontend-spec.md # React components, SSE client, state management
│ └── infrastructure-spec.md # Pulumi, ECS, RDS, ElastiCache, Amplify
│
├── architecture/ # System architecture
│ └── system-overview.md # Multi-repo structure, data flow, tech stack
│
├── business/ # Business context (informational, not prescriptive)
│ ├── mvp-definition.md # MVP scope, timeline, success criteria
│ ├── business-plan.md # Market analysis, revenue model
│ ├── development-roadmap.md # Phase 1-4 feature timeline
│ ├── executive-brief.md # Executive summary
│ ├── ai-team-strategy.md # AI team composition
│ ├── branding-guide.md # Brand identity
│ └── sage-overview-kr.md # Overview (Korean)
│
├── product/ # Product requirements
│ └── product-spec.md # Features, user journeys, Agent Pipeline
│
├── operations/ # GTM and operations
│ ├── operations-roadmap.md # Operations timeline
│ ├── genesis-operations.md # Launch operations
│ ├── live-ops-playbook.md # Live operations guide
│ ├── mystery-campaign.md # Mystery campaign strategy
│ └── discord-management.md # Discord community management
│
├── docs/ # Legacy documentation (to be migrated)
│ ├── technical/ # Old specs (use specs/ instead)
│ └── ai-guides/ # Claude Code development guides
│
├── wiki/ # GitHub Wiki sync (auto-generated, do not edit)
│
├── CLAUDE.md # AI development constitution
├── README.md # This file
└── README-kr.md # Korean version
-
Read the specs first:
- Backend:
specs/backend-spec.md - Frontend:
specs/frontend-spec.md - Infrastructure:
specs/infrastructure-spec.md
- Backend:
-
Understand the architecture:
-
Check MVP scope:
- Read
CLAUDE.mdfirst - it's the constitution for AI development - Always reference
specs/when implementing features - Follow terminology guidelines (Agent Pipeline, not "multi-agent system")
- Preserve performance targets: <2s first token, <0.5s context load
- Framework: React 18.3 + Vite 5
- State: Zustand 4.x (client), TanStack Query 5.x (server)
- Styling: Tailwind CSS 3.x + shadcn/ui
- Real-time: SSE (Server-Sent Events) for AI streaming
- Framework: Nest.js 10.x
- Database: PostgreSQL 18 (via Prisma 5.x)
- Cache: Valkey 8.x (Redis-compatible)
- AI: Claude Sonnet 4 + Haiku 4 (@anthropic-ai/sdk)
- Auth: Auth.js with Google OAuth
- IaC: Pulumi 3.x (TypeScript)
- Compute: AWS ECS Fargate
- Database: AWS RDS PostgreSQL 18
- Cache: AWS ElastiCache Valkey 8.x
- CDN: AWS Amplify (frontend), CloudFront
- LB: AWS ALB
- Agent Pipeline: Manager → Analyst → Persona → Risk
- Streaming: SSE for token-by-token response (<2s first token)
- Context: 20-message window (no RAG in MVP)
- Virtual Trading: No real money, practice-only
- AI Signals: Extracted from chat conversations
- Performance: Historical performance tracking
- Market Alerts: BTC -5%, ETH -7% triggers notification
- Deep Links: Push notification → Auto-open chat with context
- Multi-channel: PWA push + Discord webhook
Code repositories contain local copies of relevant specs:
# Frontend repo
sage-front/docs/frontend-spec.md # Copied from specs/frontend-spec.md
# Backend repo
sage-back/docs/backend-spec.md # Copied from specs/backend-spec.md
# Infrastructure repo
sage-infra/docs/infrastructure-spec.md # Copied from specs/infrastructure-spec.mdWhen updating specs:
- Edit in
sage-docs/specs/(Source of Truth) - Copy to relevant code repository
- Commit with message:
Sync [spec] from sage-docs@[commit-hash]
Example:
# Update frontend spec in sage-docs
cd sage-docs
git commit specs/frontend-spec.md -m "Update SSE reconnection logic"
git push
# Sync to frontend repo
cd ../sage-front
cp ../sage-docs/specs/frontend-spec.md docs/
git commit docs/frontend-spec.md -m "Sync frontend-spec from sage-docs@abc123"
git pushThese are hard requirements, not suggestions:
| Metric | Target | Measurement |
|---|---|---|
| SSE First Token | < 2s | Time from POST to first SSE token |
| Context Load | < 0.5s | Fetch 20 messages from PostgreSQL |
| API Response | < 200ms (P95) | REST endpoint latency |
| Cache Hit Rate | > 80% | Valkey hit/miss ratio |
| Hallucination Rate | < 1% | Risk Agent rejection rate |
Use these terms correctly in all documentation and code:
| Correct Term | Definition | Wrong Usage |
|---|---|---|
| Agent Pipeline | Manager → Analyst → Persona → Risk sequence | ❌ "multi-agent system" |
| Agent | Functional unit within ONE persona (Manager, Analyst, etc.) | ❌ Agent = Persona |
| Persona | Character + LLM combination (Warren Buffett + Claude) | ❌ "agent" when referring to persona |
| SSE Streaming | Server-Sent Events for AI response | ❌ "WebSocket" (not used in MVP) |
| Shadow Portfolio | Virtual/practice portfolio | ❌ "paper trading", "simulated" |
- ✅ Tech stack finalized
- ✅ Specs written (backend, frontend, infrastructure)
- ✅ Repository split planned
- 🔄 Amplify migration planned
- 🔄 SSE vs WebSocket decision: Keep SSE
- Create sage-infra repository
- Define Pulumi resources (ECS, RDS, ElastiCache)
- Set up AWS Amplify app via Pulumi
- Create sage-back repository
- Implement Agent Pipeline
- Set up SSE streaming endpoints
- Connect to Claude API
- Create sage-front repository
- Implement SSE client
- Build chat interface
- Deploy to Amplify
-
Specs (
specs/): Create PR with clear description -
Architecture (
architecture/): Discuss with team first -
Business/Product (
business/,product/): Requires product owner approval -
Operations (
operations/): Requires operations lead approval
Go to the relevant code repository:
- Frontend changes → sage-front
- Backend changes → sage-back
- Infrastructure changes → sage-infra
- Independent deployment cycles: Frontend, backend, infra deploy at different rates
- Team autonomy: Each team can work independently
- Clearer boundaries: Docs vs code separation
- Simplified CI/CD: Each repo has focused pipelines
- Complexity: Submodules add overhead (init, update, nested commits)
- Independence: Each repo should work standalone
- Simplicity: Copy + README link is simpler for our team size
- Automatic deployment: Git push → auto build (no GitHub Actions needed)
- PR previews: Auto preview URL for every PR
- Simplicity: Less manual configuration
- MVP speed: Faster time to market
Possibly in Phase 2+ if we add:
- Real-time collaborative features (group chat, shared portfolio)
- Live market data streaming to UI (ticker)
- User interrupt during AI response
For MVP, SSE is sufficient and simpler.
- GitHub Issues: sage-docs/issues
- Discord: (to be added)
- Email: (to be added)
(To be determined)
Last Updated: 2026-01-05 Migration Status: Converted from monorepo to multi-repository structure
🏠 Home
- 📚 sage-docs (Documentation)
- 🎨 sage-frontend (React App)
- ⚙️ sage-backend (Nest.js API)
- 🏗️ sage-infra (Pulumi IaC)