Claude Built Stack

克劳德建造堆栈

一个全栈网络平台，展示了使用Claude Code、MCP和AWS Bedrock的现代人工智能辅助开发。该项目展示了快速功能开发、生产就绪架构和端到端测试实践。

🎯 项目目的

这是一个投资组合/学习项目，展示了：

• 人工智能辅助开发：与Claude Code和MCP服务器协同构建
• 全栈功能：完成CRUD操作、实时流、审计日志
• 现代建筑：RESTful API、连接池、响应式前端
• 生产实践：环境管理、错误处理、安全模式

✨ 特性

广播流媒体平台

• 实时HLS流媒体：CloudFront通过HLS.js播放器支持HLS流
• SHOUTcast支持：适用于92.3 FM电台的HTML5音频播放器
• 实时元数据：基于投票的歌曲信息更新与专辑封面
• 歌曲评级系统：基于IP的评级，有赞成/反对票和持久性
• 跟踪历史记录：显示包含艺术家信息的最新歌曲

用户管理系统

• 完整的CRUD操作：创建、读取、更新、删除用户
• 电子邮件唯一性：具有适当错误处理的数据库级约束
• 审计跟踪：所有操作都记录了IP地址和更改跟踪
• RESTful API：使用正确的状态代码清理JSON端点

学生登记处

• 学术管理：学生记录，包括姓名、电子邮件、年级和专业
• 等级验证：学术水平下拉选择
• 搜索和排序：前端过滤和排序功能
• 综合审计：审计日志中跟踪的所有学生操作

审计日志

• 全面跟踪：记录所有CREATE/UPDATE/DELETE操作
• JSONB存储：使用PostgreSQL JSONB进行灵活的更改跟踪
• IP跟踪：通过请求IP地址进行用户识别
• 查询接口：通过API检索和分析审核日志

🛠️ 技术栈

后端

• 运行时：Node.js v22.21.1
• 框架：Express.js
• 数据库：PostgreSQL 17，带pg连接池
• 环境：dotenv用于配置管理

前端

• 普通JavaScript：为清楚起见，没有框架依赖关系
• HLS.js：专业级HLS流媒体库
• 响应式设计：带有RadioCalico品牌的移动优先CSS
• 获取API：现代异步HTTP请求

开发和测试工具

• AI协助：Claude Code、MCP服务器、AWS Bedrock
• 开发服务器：Nodemon用于热重载开发
• 测试：Jest（测试运行者）、Supertest（API测试）
• 版本控制：Git与GitHub
• 数据库客户端：PostgreSQL CLI工具

📡 API终点

系统健康

GET /api/health          - Health check with timestamp
GET /api/test-db         - Database connection test
GET /api/audit           - Retrieve audit logs (last 1000)

用户管理

GET    /api/users        - List all users
GET    /api/users/:id    - Get single user
POST   /api/users        - Create user (name, email)
PUT    /api/users/:id    - Update user (name, email)
DELETE /api/users/:id    - Delete user (logged)

学生管理

GET    /api/students        - List all students
GET    /api/students/:id    - Get single student
POST   /api/students        - Create student (name, email, grade, major?)
PUT    /api/students/:id    - Update student (name, email, grade, major?)
DELETE /api/students/:id    - Delete student (logged)

歌曲评级

GET  /api/ratings/:title/:artist  - Get rating counts + user's rating
POST /api/ratings                  - Submit/update rating (title, artist, rating: "up"|"down")

所有端点返回JSON status, message，以及 data 领域。错误包括适当的HTTP状态代码（400404500）。

🚀 入门指南

先决条件

选项1:Docker（推荐）

• Docker 20.10+
• Docker Compose 2.0+

方案2：地方发展

• Node.js v22.21.1或更高版本
• PostgreSQL 17
• npm或纱线

Docker部署（推荐）

运行应用程序的最简单方法：

1. 克隆仓库

git clone https://github.com/tech-uprise/claude-built-stack.git
cd claude-built-stack

1. 创建环境文件

cp .env.docker.example .env
# Edit .env if needed (defaults work for local development)

1. 从Docker Compose开始

docker-compose up -d

1. 验证部署

# Check containers are running
docker-compose ps

# View logs
docker-compose logs -f app

# Check health
curl http://localhost:3000/api/health

1. 访问应用程序

• 主页：http://localhost:3000
• API文件：http://localhost:3000/api-docs.html
• 所有功能均已准备就绪！

Docker命令：

docker-compose up -d          # Start in background
docker-compose down           # Stop and remove containers
docker-compose logs -f app    # View app logs
docker-compose logs -f db     # View database logs
docker-compose restart app    # Restart application
docker-compose exec db psql -U postgres -d radiocalco_dev  # Access database

数据库持久性：

• 数据存储在Docker卷中 radiocalco_postgres_data
• 容器重启后幸存
• 要重置： docker-compose down -v (⚠️ 删除所有数据）

本地安装（无Docker）

1. 克隆仓库

git clone https://github.com/tech-uprise/claude-built-stack.git
cd claude-built-stack

1. 安装依赖项

npm install

1. 配置环境

cp .env.example .env
# Edit .env with your database credentials

1. 启动PostgreSQL

brew services start postgresql@17

1. 创建数据库

/usr/local/opt/postgresql@17/bin/createdb radiocalco_dev

1. 初始化数据库表

/usr/local/opt/postgresql@17/bin/psql radiocalco_dev

然后从以下位置运行SQL CLAUDE.md （用户、song_ratings、audit_log、学生表）。

1. 启动开发服务器

npm run dev

1. 访问应用程序

• 主页：http://localhost:3000
• 用户管理：http://localhost:3000/users.html
• 学生登记处：http://localhost:3000/students.html
• 收音机播放器：http://localhost:3000/radio.html
• API文件：http://localhost:3000/api-docs.html

AWS生产部署

该应用程序使用多区域架构部署在AWS上。看 DEPLOYMENT.md 获取完整的部署指南。

现场制作URL: https://4g3i27nzmy.us-west-2.awsapprunner.com

建筑:

• 计算：AWS应用程序运行程序（美国西部2号，俄勒冈州）-1个vCPU，2GB RAM
• 数据库：AWS RDS PostgreSQL 17（美国西部-1，北加州）-db.t3.micro
• 注册表：亚马逊ECR（us-west-2）-Docker镜像存储
• CI/CD：GitHub Actions-自动化测试和部署

主要特点:

• 自动缩放：基于负载的1-3个实例
• 为数据库连接启用SSL/TLS
• 自动备份（7天保留期）
• 通过以下方式进行健康监测 /api/health 端点
• CloudWatch日志记录和指标

快速部署:

# See DEPLOYMENT.md for full instructions
git push origin master  # Triggers GitHub Actions workflow

有关AWS部署说明、故障排除和成本估算的详细信息，请参阅：

• DEPLOYMENT.md -AWS逐步部署指南
• ARCHITECTURE.md -系统架构和设计决策
• CLAUDE.md -AWS部署部分常见问题

🏗️ 建筑

请求流

1. Express中间件处理JSON/URL编码的主体
2. 从提供的静态文件 public/ 目录
3. API路由通过连接池查询PostgreSQL
4. 所有突变都会触发审核日志条目
5. 通过fetch（）API调用进行前端更新

数据库设计

• 连接池：pg用于高效连接的池
• 参数化查询：SQL注入预防 $1, $2... 占位符
• 约束条件：电子邮件的独特限制，评级的独特（歌曲、艺术家、ip）
• 索引：优化了song_ratings、audit_log、students的查询
• JSONB：audit_log中灵活的变更跟踪

安全

• 所有查询都使用参数化语句（无SQL注入）
• 在数据库级别强制执行电子邮件唯一性
• 处理前的输入验证
• 专门处理的错误代码23505（唯一违规）
• 为审计跟踪捕获的IP地址

前端架构

• 无需构建步骤-香草JavaScript
• 共享公用设施：常见功能 /public/js/utils.js （干燥原理）
• 从CDN加载HLS.js进行流式传输
• 一致的品牌：蒙特塞拉特/Open Sans字体，RadioCalico颜色
• 所有页面都使用fetch（）进行异步通信
• 通过以下方式预防XSS escapeHtml() 效用

📂 项目结构

claude-built-stack/
├── server.js              # Main Express app with all routes
├── db.js                  # PostgreSQL connection pool
├── Dockerfile             # Multi-stage Docker build
├── docker-compose.yml     # Orchestration for app + PostgreSQL
├── .dockerignore          # Docker build exclusions
├── init.sql               # Database initialization script
├── .env                   # Environment variables (not in git)
├── .env.example           # Example environment template (local)
├── .env.docker.example    # Example environment template (Docker)
├── package.json           # Dependencies and scripts
├── CLAUDE.md              # Claude Code project instructions
├── __tests__/             # Automated test suites
│   ├── health.test.js     # System health tests
│   ├── users.test.js      # User API tests
│   ├── students.test.js   # Student API tests
│   ├── ratings.test.js    # Rating system tests
│   ├── audit.test.js      # Audit logging tests
│   └── frontend/
│       └── utils.test.js  # Frontend utility tests
├── public/                # Static frontend files
│   ├── index.html         # Landing page
│   ├── users.html         # User management UI
│   ├── students.html      # Student registry UI
│   ├── radio.html         # HLS radio player
│   ├── radio-923.html     # SHOUTcast player
│   ├── api-docs.html      # API documentation
│   ├── audit.html         # Audit log viewer
│   ├── css/               # Stylesheets (refactored with base.css)
│   └── js/
│       └── utils.js       # Shared utility functions
└── README.md              # This file

🧪 测试

自动化测试（Jest+Supertest）

运行所有测试：

npm test                # Run all tests with coverage
npm run test:watch      # Watch mode for development
npm run test:ci         # CI mode (no interactive prompts)

测试覆盖范围：

• 6个测试套件，共67个测试
• 后端（45次测试）：API端点、数据库操作、错误处理
• 前端（22次测试）：实用函数、DOM操作、验证
• 覆盖：约85%用于server.js和db.js

后端测试：

• health.test.js -系统健康和数据库连接（2个测试）
• users.test.js -带验证的用户CRUD操作（17次测试）
• students.test.js -带有审计日志的学生管理（17项测试）
• ratings.test.js -歌曲评级系统和持久性（9项测试）
• audit.test.js -审计跟踪验证（5项测试）

前端测试：

• utils.test.js -实用函数：escapeHtml、showMessage、formatDate、formatTimestamp、getFormData、isValidEmail（22个测试）

手动测试

手动验证：

1. 使用启动服务器 npm run dev
2. 验证数据库http://localhost:3000/api/test-db
3. 通过API-docs.html测试API端点
4. 通过radio.html和radio-923.html测试无线电流
5. 通过users.html和students.html测试CRUD操作

🎨 品牌指南

RadioCalico品牌使用：

• 颜色：薄荷（#D8F2D5）、森林绿（#1F4E23）、青色（#38A29D）、加州橙（#EFA63C）、木炭（#231F20）、奶油（#F5EADA）
• 排版蒙特塞拉特（标题）、Open Sans（正文）
• 标志：RadioCalicoLogoTM.png（带耳机的猫）

看 RadioCalico_Style_Guide.txt 完整的指南。

🤖 AI开发流程

该项目利用了：

• 克劳德代码：用于快速功能开发的AI配对编程
• MCP（模型上下文协议）：增强上下文和工具集成
• AWS基岩：\[计划\]人工智能模型部署和扩展
• 迭代开发：满足需求的人工智能协作→ 实施→ 测试

关键学习成果

• 有效的人工智能辅助全栈开发
• RESTful API的设计与实现
• PostgreSQL模式设计与优化
• 现代JavaScript模式（async/await、fetch）
• 生产就绪错误处理
• 数据库连接管理
• 安全最佳实践（SQL注入预防、输入验证）

📝 可用脚本

npm start           # Production server
npm run dev         # Development server with auto-reload
npm test            # Run all tests with coverage
npm run test:watch  # Run tests in watch mode
npm run test:ci     # Run tests in CI mode

🔧 数据库管理

启动/停止PostgreSQL

brew services start postgresql@17
brew services stop postgresql@17
brew services list

ACCESS数据库

/usr/local/opt/postgresql@17/bin/psql radiocalco_dev

常用命令

• \l -列出数据库
• \dt -列出表格
• \d table_name -描述表格
• \q -退出

⚠️ 已知限制

• 无身份验证：用户/学生端点缺乏访问控制
• 基于IP的评级：可以通过VPN绕过
• 无速率限制：API端点不受限制
• 单个实例：不支持水平缩放

🚧 路线图

完成✅

• \[x\] 为API端点添加单元测试（Jest+Supertest）
• \[x\] 为实用程序添加前端单元测试
• \[x\] JavaScript代码重构（DRY与共享utils.js）
• \[x\] CSS重构（共享base.CSS）
• \[x\] Docker容器化与Docker组合
• \[x\] AWS生产部署（App Runner+RDS）
• \[x\] 带有GitHub操作的CI/CD管道
• \[x\] RDS连接的SSL/TLS配置
• \[x\] 多区域架构文档

进行中/计划中

• \[\]添加身份验证（基于JWT或会话）
• \[\]实施速率限制
• \[\]添加端到端测试（剧作家/赛普拉斯）
• \[\]实现WebSocket以实现实时更新
• \[\]添加用户角色和权限
• \[\]将RDS迁移到us-west-2（可选优化）
• \[\]CloudWatch仪表板和警报
• \[\]Kubernetes部署清单

📄 许可证

这是一个学习/投资组合项目。您可以自由地探索和学习代码。

🤝 贡献

这是一个个人学习项目，但欢迎通过问题提供反馈和建议。

______________________________________________________________________

使用克劳德代码构建 -展示人工智能辅助软件开发的未来。