From 528b3786b42b41368721843f93f556206fbd7949 Mon Sep 17 00:00:00 2001 From: Bill Date: Sat, 1 Nov 2025 11:17:17 -0400 Subject: [PATCH] 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 --- ...1-01-rebrand-to-ai-trader-server-design.md | 273 ++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 docs/plans/2025-11-01-rebrand-to-ai-trader-server-design.md diff --git 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 new file mode 100644 index 0000000..4fab3c7 --- /dev/null +++ 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