docs: add rebrand design document for AI-Trader-Server

Add comprehensive design document for rebranding project from AI-Trader to AI-Trader-Server. Includes 4-phase approach with validation checkpoints, naming conventions, and success criteria. Co-Authored-By: Claude <noreply@anthropic.com>
2026-04-01 17:17:24 -04:00 · 2025-11-01 11:17:17 -04:00
parent ab085e5545
commit 528b3786b4
1 changed files with 273 additions and 0 deletions
--- a/docs/plans/2025-11-01-rebrand-to-ai-trader-server-design.md
+++ b/docs/plans/2025-11-01-rebrand-to-ai-trader-server-design.md
@@ -0,0 +1,273 @@
+# AI-Trader to AI-Trader-Server Rebrand Design
+
+**Date:** 2025-11-01
+**Status:** Approved
+
+## Overview
+
+Rebrand the project from "AI-Trader" to "AI-Trader-Server" to accurately reflect its evolution into a REST API service architecture. This is a clean-break rebrand with no backward compatibility requirements.
+
+## Goals
+
+1. Update project name consistently across all documentation and configuration
+2. Emphasize REST API service architecture in messaging
+3. Update repository references to `github.com/Xe138/AI-Trader-Server`
+4. Update Docker image references to `ghcr.io/xe138/ai-trader-server`
+5. Acknowledge original fork source
+
+## Strategy: Layered Rebrand with Validation
+
+The rebrand will proceed in 4 distinct phases, each with validation checkpoints to ensure consistency and correctness.
+
+---
+
+## Phase 1: Core User-Facing Documentation
+
+### Files to Update
+- `README.md`
+- `QUICK_START.md`
+- `API_REFERENCE.md`
+- `CHANGELOG.md`
+
+### Changes
+
+#### Title & Tagline
+- **Old:** "🚀 AI-Trader: Can AI Beat the Market?"
+- **New:** "🚀 AI-Trader-Server: REST API for AI Trading"
+
+#### Subtitle/Description
+- **Old:** "REST API service for autonomous AI trading competitions..."
+- **New:** Emphasize "REST API service" as the primary architecture
+
+#### Repository URLs
+- **Old:** `github.com/HKUDS/AI-Trader` or `github.com/Xe138/AI-Trader`
+- **New:** `github.com/Xe138/AI-Trader-Server`
+
+#### Docker Image References
+- **Old:** `ghcr.io/hkuds/ai-trader:latest`
+- **New:** `ghcr.io/xe138/ai-trader-server:latest`
+
+#### Badges
+Update shields.io badge URLs and links to reference new repository
+
+### Validation Checklist
+- [ ] Render markdown locally to verify formatting
+- [ ] Test all GitHub links (repository, issues, etc.)
+- [ ] Verify Docker image references are consistent
+- [ ] Check that badges render correctly
+
+---
+
+## Phase 2: Configuration Files
+
+### Files to Update
+- `configs/*.json`
+- `.env.example`
+- `docker-compose.yml`
+- `Dockerfile`
+
+### Changes
+
+#### docker-compose.yml
+- **Service name:** Update if currently "ai-trader"
+- **Container name:** `ai-trader` → `ai-trader-server`
+- **Image name:** Update to `ai-trader-server:latest` or `ghcr.io/xe138/ai-trader-server`
+
+#### Dockerfile
+- **Labels/metadata:** Update any LABEL instructions with project name
+- **Comments:** Update inline comments referencing project name
+
+#### Configuration Files
+- **Comments:** Update JSON/config file comments with new project name
+- **Metadata fields:** Update any "project" or "name" fields
+
+#### .env.example
+- **Comments:** Update explanatory comments with new project name
+
+### Validation Checklist
+- [ ] Run `docker-compose build` successfully
+- [ ] Run `docker-compose up` and verify container name
+- [ ] Check environment variable documentation consistency
+- [ ] Verify config files parse correctly
+
+---
+
+## Phase 3: Developer & Deployment Documentation
+
+### Files to Update
+
+#### docs/user-guide/
+- `configuration.md`
+- `using-the-api.md`
+- `integration-examples.md`
+- `troubleshooting.md`
+
+#### docs/developer/
+- `CONTRIBUTING.md`
+- `development-setup.md`
+- `testing.md`
+- `architecture.md`
+- `database-schema.md`
+- `adding-models.md`
+
+#### docs/deployment/
+- `docker-deployment.md`
+- `production-checklist.md`
+- `monitoring.md`
+- `scaling.md`
+
+#### docs/reference/
+- `environment-variables.md`
+- `mcp-tools.md`
+- `data-formats.md`
+
+### Changes
+
+#### Architecture Diagrams
+Update ASCII art diagrams:
+- Any "AI-Trader" labels → "AI-Trader-Server"
+- Maintain diagram structure, only update labels
+
+#### Code Examples
+In documentation only (no actual code changes):
+- Example client class names: `AITraderClient` → `AITraderServerClient`
+- Import examples: Update project references
+- Shell script examples: Update Docker image names and repository clones
+
+#### CLAUDE.md
+- **Project Overview section:** Update project name and description
+- **Docker Deployment commands:** Update image names
+- **Repository references:** Update GitHub URLs
+
+#### Shell Scripts (if any in docs/)
+- Update comments and echo statements
+- Update git clone commands with new repository URL
+
+### Validation Checklist
+- [ ] Verify code examples are still executable (where applicable)
+- [ ] Check documentation cross-references (internal links)
+- [ ] Test Docker commands in deployment docs
+- [ ] Verify architecture diagrams render correctly
+
+---
+
+## Phase 4: Internal Configuration & Metadata
+
+### Files to Update
+- `CLAUDE.md` (main project root)
+- `.github/workflows/*.yml` (if exists)
+- Any package/build metadata files
+
+### Changes
+
+#### CLAUDE.md
+- **Project Overview:** First paragraph describing project name and purpose
+- **Commands/Examples:** Any git clone or Docker references
+
+#### GitHub Actions (if exists)
+- **Workflow names:** Update descriptive names
+- **Docker push targets:** Update registry paths to `ghcr.io/xe138/ai-trader-server`
+- **Comments:** Update inline comments
+
+#### Git Configuration
+- No changes needed to .gitignore or .git/ directory
+- Git remote URLs should be updated separately (not part of this rebrand)
+
+### Validation Checklist
+- [ ] CLAUDE.md guidance remains accurate for Claude Code
+- [ ] No broken internal cross-references
+- [ ] CI/CD workflows (if any) reference correct image names
+
+---
+
+## Naming Conventions Reference
+
+### Project Display Name
+**Format:** AI-Trader-Server (hyphenated, Server capitalized)
+
+### Repository References
+- **URL:** `https://github.com/Xe138/AI-Trader-Server`
+- **Clone:** `git clone https://github.com/Xe138/AI-Trader-Server.git`
+
+### Docker References
+- **Image:** `ghcr.io/xe138/ai-trader-server:latest`
+- **Container name:** `ai-trader-server`
+- **Service name (compose):** `ai-trader-server`
+
+### Code Identifiers
+- **Python classes:** No changes required (keep existing for backward compatibility)
+- **Documentation examples:** Optional update to `AITraderServerClient` for clarity
+
+---
+
+## Fork Acknowledgment
+
+Add the following section to README.md, placed before the "License" section:
+
+```markdown
+---
+
+## 🙏 Acknowledgments
+
+This project is a fork of [HKUDS/AI-Trader](https://github.com/HKUDS/AI-Trader), re-architected as a REST API service for external orchestration and integration.
+
+---
+```
+
+---
+
+## Implementation Notes
+
+### File Identification Strategy
+1. Use `grep -r "AI-Trader" --exclude-dir=.git` to find all references
+2. Use `grep -r "ai-trader" --exclude-dir=.git` for lowercase variants
+3. Use `grep -r "github.com/HKUDS" --exclude-dir=.git` for old repo URLs
+4. Use `grep -r "ghcr.io/hkuds" --exclude-dir=.git` for old Docker images
+
+### Testing Between Phases
+- After Phase 1: Review user-facing documentation for consistency
+- After Phase 2: Test Docker build and deployment
+- After Phase 3: Verify all documentation examples
+- After Phase 4: Full integration test
+
+### Rollback Plan
+If issues arise:
+1. Each phase should be committed separately
+2. Use `git revert` to roll back individual phases
+3. Re-validate after any rollback
+
+---
+
+## Success Criteria
+
+- [ ] All references to "AI-Trader" updated to "AI-Trader-Server"
+- [ ] All GitHub URLs point to `Xe138/AI-Trader-Server`
+- [ ] All Docker references use `ghcr.io/xe138/ai-trader-server`
+- [ ] Fork acknowledgment added to README
+- [ ] Docker build succeeds with new naming
+- [ ] All documentation links verified working
+- [ ] No broken cross-references in documentation
+
+---
+
+## Out of Scope
+
+The following items are **not** part of this rebrand:
+
+- Changing Python class names (e.g., `BaseAgent`, internal classes)
+- Updating actual git remote URLs (handled separately by user)
+- Publishing to Docker registry (deployment task)
+- Updating external references (blog posts, social media, etc.)
+- Database schema or table name changes
+- API endpoint paths (remain unchanged)
+
+---
+
+## Timeline Estimate
+
+- **Phase 1:** ~15-20 minutes (4 core docs files)
+- **Phase 2:** ~10-15 minutes (configuration files and Docker)
+- **Phase 3:** ~30-40 minutes (extensive documentation tree)
+- **Phase 4:** ~10 minutes (internal metadata)
+
+**Total:** ~65-85 minutes of focused work across 4 validation checkpoints