llm-driven-system-design: Instructions file for Codex

AGENTS.md

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

Table of Contents

• Repository Overview
• Quick Start for Any Project
• Project Structure
  • Writing Architecture Documents
  • Writing System Design Answers
  • Explaining Trade-offs in Depth
• Common Commands
• Repository Scripts
• CI/CD
• Technology Stack Defaults
• Key Design Principles
• Port Conventions
• Frontend Best Practices
• Backend Architecture Pattern
• Database Selection Guide
• Creating New Projects
• Local Development Philosophy
• Infrastructure Options
• ESM Import Convention

Repository Overview

This is a system design learning repository where each subdirectory represents an independent system design challenge. Most projects have both design documentation and working implementations.

Node.js Requirement: >=20.0.0

Quick Start for Any Project

1. Read the project's architecture.md first to understand the design
2. Check AGENTS.md for iteration history and key decisions (primary source of truth for project-specific guidance - captures the "why" behind implementation choices)
3. Look at README.md for setup instructions
4. Check package.json to find available scripts

Project Structure

Each project folder typically contains:

<project>/
├── README.md                  # Setup instructions and implementation guide
├── architecture.md            # System design documentation and trade-offs
├── system-design-answer-frontend.md   # Frontend-focused interview answer
├── system-design-answer-backend.md    # Backend-focused interview answer
├── system-design-answer-fullstack.md  # Full-stack interview answer
├── AGENTS.md                  # LLM collaboration notes and iteration history
├── frontend/                  # React + TypeScript frontend (when applicable)
├── backend/                   # Node.js + Express backend (when applicable)
├── training/                  # ML training code (Python, when applicable)
└── docker-compose.yml         # Infrastructure services (PostgreSQL, Redis, etc.)