Skip to content

AGENTS.md

Latest commit

 

History

History
267 lines (204 loc) · 9.91 KB

AGENTS.md

File metadata and controls

267 lines (204 loc) · 9.91 KB
Raw

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Custom Instructions

Communication

  • Primary Language: 日本語でのやりとりを基本とする (Use Japanese as the primary communication language)

External Content Management

  • MCP Server Changes: MCPサーバーで外部コンテンツに変更を加える時は、必ず事前に確認をとること (Always seek confirmation before making changes to external content via MCP servers)

Git Commit Guidelines

  • Commit Granularity: gitコミットは適切な粒度にわけて簡潔なコミットメッセージにより行うこと (Make git commits with appropriate granularity and concise commit messages)

Pull Requests（ベースブランチ）

  • 既定のマージ先: 通常の開発用 PR は dev をベースにする（main は本番相当のため、ここへ向けない）。ユーザーが別ブランチを明示したときのみ従う。
  • gh pr create: ベース未指定だとリポジトリ既定（多くの場合 main）になりやすいので、必ず --base dev を付ける（または GitHub 上でベースを dev に変更する）。

Communication Style

  • Ask Questions: 指示が曖昧だったり、不明点・懸念点があれば遠慮なく質問・確認すること (Don't hesitate to ask questions or seek clarification when instructions are ambiguous or when there are unclear points or concerns)

Project Overview

YouTube Study Space is a 24/7 automated online study room livestreamed on YouTube. Users can join and leave virtual study sessions through YouTube live chat commands. The system supports both general seats and member-exclusive seats, tracks work time, and provides moderation and automation features.

Development Commands

Go Backend (system/)

# Run the main bot locally
go run ./cmd/youtube-bot

# Run all tests with randomization
go test -shuffle=on -v ./...

# Run tests for a specific package
go test ./core/youtubebot/...

# Generate repository mocks
mockgen -source ./core/repository/interface.go -destination ./core/repository/mocks/interface.go -package mock_repository

# Update dependencies
go mod tidy

# Regenerate typed i18n wrappers
go generate ./...

Frontend (youtube-monitor/)

# Install dependencies
pnpm install

# Development server
pnpm dev

# Production build
pnpm build

# Production server
pnpm start

# Run tests
pnpm test

# Linting and formatting (using Biome)
pnpm format
pnpm lint
pnpm lint:fix
pnpm format:fix

# Storybook for component development
pnpm storybook
pnpm build-storybook

AWS Infrastructure (aws-cdk/)

# Install dependencies
pnpm install

# Preview infrastructure changes
pnpm cdk:diff

# Deploy infrastructure
pnpm cdk:deploy

# Build CDK code
pnpm build

# Run CDK tests
pnpm test

Documentation Site (docs-site/)

# Install dependencies
pnpm install

# Local development server
pnpm start

# Build static site
pnpm build

# Formatting and linting
pnpm format
pnpm lint

  • Note: In docs-site/, pnpm format runs biome format --write . (writes files), while youtube-monitor/ uses separate format vs format:fix scripts. docs-site pnpm check runs biome check --apply ..

  • youtube-monitor/, aws-cdk/, and docs-site/ use pnpm (packageManager: pnpm@10.4.0).

  • Do not use npm or yarn for these directories unless explicitly required.

Architecture

High-Level Structure

  • system/ - Go backend, scheduled jobs, and AWS Lambda entrypoints
  • youtube-monitor/ - Next.js frontend for the study room interface
  • aws-cdk/ - AWS infrastructure as code
  • docs-site/ - Docusaurus documentation site with i18n support
  • firebase/ - Firestore configuration

Core Architecture Patterns

Event-Driven Serverless:

  • Every 1 minute: youtube_organize_database + check_live_stream_status
  • Every 15 minutes: update_work_name_trend
  • Daily at 00:00 JST: EventBridge Scheduler invokes start_daily_batch, which starts Step Functions; after a built-in 15-second wait (date-boundary safeguard in CDK), the state machine runs the sequential ECS Fargate daily batch (reset-daily-total → update-rp → transfer-bq)

Multi-Database Strategy:

  • Firestore: Real-time user sessions, room state, chat history, configuration
  • DynamoDB: Configuration and secret lookup for Lambda-side operations
  • BigQuery: Historical analytics and archival processing
  • Cloud Storage: Transfer source for BigQuery import jobs

Command Processing Flow:

  1. YouTube Live Chat API retrieves messages
  2. Commands are parsed and validated
  3. workspaceapp processes seat, break, user, and moderation behavior
  4. Firestore transactions persist state changes
  5. Replies and notifications are posted to YouTube Live Chat and Discord when needed

Key Components

Backend (system/core/):

  • workspaceapp/ - Main application layer for command handling, presenters, validation, and batch jobs
  • youtubebot/ - YouTube Live Chat API integration
  • repository/ - Firestore data access layer
  • guardians/ - Live stream monitoring and guard logic
  • moderatorbot/ - Moderation and Discord notification integrations
  • mybigquery/ - BigQuery transfer logic
  • i18n/ - Locales and typed translation wrappers

Backend Entrypoints (system/):

  • cmd/youtube-bot/ - Local live chat bot runner
  • cmd/batch/ - Daily batch executable for Fargate
  • cmd/lambda/ - Lambda handlers such as youtube_organize_database, check_live_stream_status, start_daily_batch, set_desired_max_seats, and update_work_name_trend

Frontend Architecture:

  • Next.js with TypeScript
  • Redux Toolkit for state management
  • Emotion for CSS-in-JS styling
  • SWR for data fetching
  • Framer Motion for animations
  • next-i18next for localization

Data Models

Core Entities

  • SeatDoc: Seat information such as user ID, entry time, and work content
  • UserDoc: User profiles and accumulated activity
  • ConstantsConfigDoc: Runtime constants such as seat counts and polling settings
  • CredentialsConfigDoc: Authentication and configuration references

State Management

  • Firestore transactions ensure atomicity for seat assignment and updates
  • User sessions persist across reconnections
  • Frontend consumes real-time data via Firebase and SWR-based flows

Testing Strategy

Go Backend

  • Standard Go testing with testify
  • Mock generation using go.uber.org/mock
  • Package-level tests around command parsing, repository behavior, and workspace flows

Frontend

  • Jest with React Testing Library
  • ts-jest for TypeScript support
  • jsdom environment for DOM testing
  • Component development and verification with Storybook

Infrastructure

  • CDK unit tests for schedule and infrastructure invariants
  • GitHub Actions CI/CD pipeline

Code Guidelines

Important Conventions

  • Preserve NOTE comments: These contain important implementation details and should not be removed
  • Add review comments: Use [NOTE FOR REVIEW] prefix for temporary explanatory comments
  • Error handling: Include contextual information in error messages
  • Transaction safety: Use Firestore transactions for data consistency

Command System

Representative chat commands (full strings and member variants live in system/core/utils/constants.go):

  • !in - General seat entry
  • /in - Member seat entry
  • !out - Exit seat
  • !break / !rest / !chill - Start break
  • !resume - End break
  • !my - Show personal stats or update personal settings
  • !rank - Display rankings
  • !more / !okawari - Extend work time
  • Moderation: !kick, !check, !block (member-prefixed variants such as /kick are defined alongside)

Internationalization

  • Support for English, Japanese, and Korean locale files
  • Message templates live under system/core/i18n/
  • system/core/i18n/generate.go wires //go:generate go run app.modules/cmd/i18n-gen; run go generate ./... from system/ to regenerate typed wrappers (and any other go:generate targets such as repository mocks)
  • Frontend uses next-i18next

Development Environment

Required Setup

  1. Go 1.25.0+ for backend development
  2. Node.js >=20.19.0 (see youtube-monitor/package.json engines) and pnpm for frontend and TypeScript-based subprojects
  3. Google Cloud credentials for Firestore, Cloud Storage, and BigQuery access
  4. AWS credentials for Lambda, Step Functions, Scheduler, and CDK operations
  5. YouTube Data API credentials

Local Development

  • system/cmd/youtube-bot runs the live chat bot locally
  • Install frontend dependencies with pnpm install in youtube-monitor/
  • Start the frontend dev server with pnpm dev in youtube-monitor/
  • Start the frontend production server with pnpm start in youtube-monitor/ on port 18080
  • Storybook runs on port 6006
  • Use .env files for local configuration

Deployment

  • AWS Lambda functions are containerized with system/Dockerfile.lambda
  • Daily batch jobs run on ECS Fargate via system/Dockerfile.fargate
  • Daily orchestration is driven by EventBridge Scheduler and Step Functions
  • Infrastructure changes are managed through aws-cdk/

External Integrations

Google Services

  • YouTube Data API v3: Live chat message retrieval and posting
  • Firestore: Primary real-time datastore
  • BigQuery: Analytics and history transfer target
  • Cloud Storage: Export and transfer staging

AWS Services

  • Lambda: Scheduled and on-demand compute
  • EventBridge / EventBridge Scheduler: Periodic execution and daily scheduling
  • Step Functions: Daily batch orchestration
  • ECS Fargate: Daily batch runtime
  • DynamoDB: Configuration storage for Lambda functions
  • API Gateway: Authenticated REST API

Third-Party

  • Discord: Notification webhooks for moderation and failures
  • OpenAI API: Work name trend generation