SYSTEM_OVERVIEW.json

{
  "system": {
    "title": "React Agent - Complete System with Custom Server",
    "overview": "System with custom FastAPI server that replaces langgraph dev, maintaining compatibility with Next.js frontend and LangGraph SDK",
    "architecture": {
      "layers": [
        {
          "name": "Frontend Layer",
          "components": [
            {
              "component": "Next.js UI",
              "port": 3000,
              "description": "Reactive user interface with chat streaming",
              "subcomponents": [
                {
                  "name": "LangGraph SDK Client",
                  "function": "Client for backend communication"
                }
              ]
            }
          ]
        },
        {
          "name": "Server Layer",
          "components": [
            {
              "component": "FastAPI Server",
              "port": 2024,
              "description": "Custom API gateway (~170 lines of code)",
              "subcomponents": [
                {
                  "name": "10 REST Endpoints",
                  "function": "Complete API for LangGraph SDK compatibility"
                },
                {
                  "name": "SSE Streaming",
                  "function": "Server-Sent Events for real-time responses"
                }
              ]
            }
          ]
        },
        {
          "name": "Agent Layer",
          "components": [
            {
              "component": "LangGraph ReAct Agent",
              "description": "Reasoning + Acting pattern with LangGraph",
              "subcomponents": [
                {
                  "name": "OpenAI GPT-4o",
                  "function": "Language model for processing"
                },
                {
                  "name": "Search Tool",
                  "function": "Integrated tools for search"
                }
              ]
            }
          ]
        },
        {
          "name": "Persistence Layer",
          "components": [
            {
              "component": "InMemorySaver Checkpointer",
              "description": "Conversation persistence system",
              "subcomponents": [
                {
                  "name": "Thread State",
                  "function": "Conversation metadata (step, status, config)"
                },
                {
                  "name": "Message Array",
                  "function": "Message sequence (human, ai, tool)"
                }
              ]
            }
          ]
        }
      ]
    },
    "api_endpoints": [
      {
        "endpoint": "/info",
        "method": "GET",
        "description": "Server status"
      },
      {
        "endpoint": "/assistants/{id}",
        "method": "GET",
        "description": "Assistant information"
      },
      {
        "endpoint": "/assistants/{id}/graph",
        "method": "GET",
        "description": "Graph schema (empty)"
      },
      {
        "endpoint": "/assistants/{id}/schemas",
        "method": "GET",
        "description": "Schemas (empty)"
      },
      {
        "endpoint": "/assistants/{id}/subgraphs",
        "method": "GET",
        "description": "Subgraphs (empty array)"
      },
      {
        "endpoint": "/assistants/search",
        "method": "POST",
        "description": "Search assistants"
      },
      {
        "endpoint": "/threads",
        "method": "POST",
        "description": "Create new conversation thread"
      },
      {
        "endpoint": "/threads/search",
        "method": "POST",
        "description": "Search threads (returns empty array)"
      },
      {
        "endpoint": "/threads/{id}/history",
        "method": "POST",
        "description": "Retrieve conversation history"
      },
      {
        "endpoint": "/threads/{id}/runs/stream",
        "method": "POST",
        "description": "Execute and stream agent response"
      }
    ],
    "checkpointer": {
      "name": "InMemorySaver",
      "description": "Core of conversation persistence",
      "thread_state_metadata": {
        "checkpoint_id": "UUID unique identifier for checkpoint state",
        "thread_id": "UUID conversation identifier for isolation",
        "step": "Incremental counter of executed LangGraph workflow steps",
        "graph_id": "Identifier of the running LangGraph graph",
        "next": "Array of LangGraph nodes to execute in next step",
        "tasks": "Array of pending tasks in workflow execution",
        "interrupts": "Array of workflow interruptions for user input",
        "timestamp": "ISO8601 timestamp of checkpoint creation"
      },
      "message_array_structure": {
        "messages": "Sequential array of LangGraph Message objects",
        "type": "Message type enum (human|ai|tool|system)",
        "content": "String textual content of the message",
        "id": "UUID unique message identifier",
        "tool_calls": "Array of tool calls for AI messages",
        "tool_call_id": "Reference ID for tool response messages",
        "additional_kwargs": "Dict of additional message-specific metadata",
        "response_metadata": "Dict of response metadata from LLM provider"
      }
    },
    "workflow_phases": [
      {
        "phase": "PHASE 1: System Initialization",
        "endpoints": [
          "GET /info",
          "GET /assistants/{id}",
          "GET /assistants/{id}/graph",
          "GET /assistants/{id}/schemas",
          "GET /assistants/{id}/subgraphs",
          "POST /assistants/search"
        ]
      },
      {
        "phase": "PHASE 2: Thread Creation",
        "endpoints": [
          "POST /threads",
          "POST /threads/search",
          "POST /threads/{id}/history"
        ]
      },
      {
        "phase": "PHASE 3: Message Processing",
        "endpoints": [
          "POST /threads/{id}/runs/stream"
        ]
      },
      {
        "phase": "PHASE 4: History Update",
        "endpoints": [
          "POST /threads/{id}/history"
        ]
      }
    ],
    "key_components": [
      {
        "name": "FastAPI Server",
        "file": "server.py",
        "port": 2024,
        "function": "API gateway that translates frontend requests to LangGraph",
        "features": [
          "Manages checkpointer for conversation history",
          "SSE for real-time responses"
        ]
      },
      {
        "name": "LangGraph ReAct Agent",
        "file": "graph.py",
        "model": "OpenAI GPT-4o",
        "features": [
          "Integrated search tool",
          "InMemorySaver for session persistence",
          "ReAct pattern (Reasoning + Acting)"
        ]
      },
      {
        "name": "Next.js Frontend",
        "directory": "agent-chat-ui/",
        "features": [
          "LangGraph SDK for communication",
          "Chat interface with streaming",
          "Automatically retrieves thread history"
        ]
      }
    ],
    "features": {
      "functional": [
        "Persistent conversations between page refreshes",
        "Real-time response streaming", 
        "Full compatibility with LangGraph SDK",
        "Integrated tool calling (search)",
        "Zero configuration deployment"
      ],
      "technical": [
        "Minimalist: ~170 lines of code",
        "Production-ready: Error handling, appropriate logging",
        "Performant: Optimized SSE streaming",
        "Scalable: Decoupled architecture"
      ]
    },
    "startup_commands": {
      "backend": {
        "command": "python src/react_agent/server.py",
        "directory": "/Users/nicco/Desktop/react-agent"
      },
      "frontend": {
        "command": "npm run dev",
        "directory": "/Users/nicco/Desktop/react-agent/agent-chat-ui"
      }
    },
    "access_urls": {
      "frontend": "http://localhost:3000",
      "backend_api": "http://localhost:2024",
      "api_docs": "http://localhost:2024/docs"
    }
  }
}