# isavage05/pair_programmer architecture

> Architecture diagram of the GitHub repository isavage05/pair_programmer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/isavage05/pair_programmer
- Repository: https://github.com/isavage05/pair_programmer

## Overview

##### Project Type and Purpose
- This is a full-stack AI-Assisted Coding Platform:
- Frontend: React.js application providing pages for task selection, code editing, learning modules, and quizzes.
- Backend: FastAPI service exposing REST endpoints, orchestrating AI-powered features (code hints, generation), code execution, learning content, and quizzes.
- Goal: Let users pick coding tasks, get AI help in real time, run/verify code, and learn via tutorial or quiz modules.

##### File Structure
- Top-level directories:
- frontend/ – React app (pages, store, public).
- backend/ – FastAPI app (app/main.py, api/routes.py, models/, services/).
- Key backend services:
ai_service.py (interacts with AI model provider)
code_executor.py (runs user code in sandbox)
code_service.py (manages code submission workflow)
learning_service.py & quiz_service.py (generate learning content/quizzes).
- Models directory holds data schemas (Task, etc.).
- Configuration & startup: package.json, requirements.txt, uvicorn command.

##### Extract Additional Insights from README
- Uses React Context or a store (codingStore.js) for state management across pages.
- Frontend calls backend endpoints for tasks, AI hints, code exec, learning, quizzes.
- Backend dependencies: FastAPI, Pydantic, HTTP client for AI API, sandbox utils.

a. Main Components
- Web Browser (React App)
- React Pages & State Store
- HTTP/HTTPS Layer (API client)
- FastAPI Backend
- Internal Service Layer (AI Service, Code Executor, Learning Service, Quiz Service)
- Data Models & Storage (Task definitions, user progress—could be a database or in-memory store)
- External Systems: AI Model Provider (e.g., OpenAI API), Code Execution Sandbox or Container

b. Relationships & Interactions
1. User interacts with the React App in the browser.
2. React pages dispatch requests via the API service functions to FastAPI endpoints.
3. FastAPI API routes forward calls to the service layer.
4. AI Service contacts the external AI API.
5. Code Executor spins up a sandbox/container to run user code and returns results.
6. Learning & Quiz Services generate content (possibly based on AI or static templates).
7. Services read/write from a data storage layer (database or in-memory cache).
8. Responses flow back up to the frontend for display.

c. Architectural Patterns & Principles
- Layered Architecture: Presentation (React) → API layer → Service layer → Data/External services.
- Separation of Concerns: Each backend service (AI, code execution, content) is decoupled.
- 12-Factor App principles: Config via requirements, package files,  environment-agnostic.
- Single-Page Application on front end, RESTful back end.

d. Key Technologies & Frameworks
- Frontend: React.js, React Router (pages), Context/API store (codingStore.js), Axios or fetch in services.
- Backend: FastAPI (uvicorn), Pydantic models, HTTPX or requests for external AI API, Docker or a sandboxing library for code execution.
- Data Storage: PostgreSQL/MySQL/Redis (if present) or file-based/in-memory for Task models.

##### Essential Details to Capture
- API boundary (REST layer).
- Service orchestration (which service calls which external system).
- Data flow: sequence of request → processing → response.
- Technology annotations (React.js, FastAPI, Pydantic, Docker/sandbox, AI API).
- CI/CD or deployment notes (if applicable—e.g., uvicorn, npm start, Docker build).

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Frontend Zone
  subgraph "Frontend"
    direction TB
    Browser["Web Browser\n(React App)"]:::frontend
    Index["index.js"]:::frontend
    App["App.js"]:::frontend
    Pages_TS["TaskSelection.js"]:::frontend
    Pages_CE["CodeEditor.js"]:::frontend
    Pages_LM["Learning.js"]:::frontend
    Pages_QZ["Quiz.js"]:::frontend
    Store["codingStore.js"]:::frontend
    APIClient["API Service\n(axios/fetch)"]:::frontend
    FDeps["package.json\n(frontend)"]:::frontend
  end

  %% Backend Zone
  subgraph "Backend"
    direction TB
    Main["main.py"]:::backend
    Router["routes.py\n(API Endpoints)"]:::backend
    Models["task.py\n(Data Models)"]:::backend
    Service_CodeSub["code_service.py"]:::backend
    Service_AI["ai_service.py"]:::backend
    Service_Exec["code_executor.py"]:::backend
    Service_Learn["learning_service.py"]:::backend
    Service_Quiz["quiz_service.py"]:::backend
    StoreDB["Database"]:::db
    DepBE["requirements.txt"]:::backend
  end

  %% External Systems
  subgraph "External Systems"
    direction TB
    AIProvider["AI Model Provider"]:::external
    Sandbox["Code Execution Sandbox"]:::external
    RootDeps["package.json\n(root)"]:::external
  end

  %% Connections Frontend
  Browser --> Index
  Index --> App
  App --> Pages_TS
  App --> Pages_CE
  App --> Pages_LM
  App --> Pages_QZ
  Pages_TS --> Store
  Pages_CE --> Store
  Pages_LM --> Store
  Pages_QZ --> Store
  Store --> APIClient
  APIClient --> Main

  %% Connections Backend
  Main --> Router
  Router --> Service_CodeSub
  Router --> Service_AI
  Router --> Service_Learn
  Router --> Service_Quiz
  Router --> Service_Exec
  Service_CodeSub --> Service_Exec
  Service_CodeSub --> Service_AI
  Service_AI --> AIProvider
  Service_Exec --> Sandbox
  Service_Learn --> Models
  Service_Quiz --> Models
  Service_CodeSub --> Models
  Models --> StoreDB
  Service_AI --> Models
  DepBE --- Router

  %% Dependencies to root
  RootDeps --- Main
  FDeps --- APIClient

  %% Click Events
  click Pages_TS "https://github.com/isavage05/pair_programmer/blob/main/frontend/src/pages/TaskSelection.js"
  click Pages_CE "https://github.com/isavage05/pair_programmer/blob/main/frontend/src/pages/CodeEditor.js"
  click Pages_LM "https://github.com/isavage05/pair_programmer/blob/main/frontend/src/pages/Learning.js"
  click Pages_QZ "https://github.com/isavage05/pair_programmer/blob/main/frontend/src/pages/Quiz.js"
  click Store "https://github.com/isavage05/pair_programmer/blob/main/frontend/src/store/codingStore.js"
  click Index "https://github.com/isavage05/pair_programmer/blob/main/frontend/src/index.js"
  click App "https://github.com/isavage05/pair_programmer/blob/main/frontend/src/App.js"
  click Main "https://github.com/isavage05/pair_programmer/blob/main/backend/app/main.py"
  click Router "https://github.com/isavage05/pair_programmer/blob/main/backend/app/api/routes.py"
  click Models "https://github.com/isavage05/pair_programmer/blob/main/backend/app/models/task.py"
  click Service_AI "https://github.com/isavage05/pair_programmer/blob/main/backend/app/services/ai_service.py"
  click Service_Exec "https://github.com/isavage05/pair_programmer/blob/main/backend/app/services/code_executor.py"
  click Service_CodeSub "https://github.com/isavage05/pair_programmer/blob/main/backend/app/services/code_service.py"
  click Service_Learn "https://github.com/isavage05/pair_programmer/blob/main/backend/app/services/learning_service.py"
  click Service_Quiz "https://github.com/isavage05/pair_programmer/blob/main/backend/app/services/quiz_service.py"
  click DepBE "https://github.com/isavage05/pair_programmer/blob/main/backend/requirements.txt"
  click FDeps "https://github.com/isavage05/pair_programmer/blob/main/frontend/package.json"
  click RootDeps "https://github.com/isavage05/pair_programmer/blob/main/package.json"

  %% Styles
  classDef frontend fill:#D6E9FE,stroke:#0052CC,color:#000
  classDef backend fill:#E6F4EA,stroke:#2E7D32,color:#000
  classDef external fill:#F0F0F0,stroke:#666,color:#000
  classDef db shape:cylinder,fill:#FFF2CC,stroke:#996600,color:#000
  classDef backend,external,frontend db
  class Browser,Index,App,Pages_TS,Pages_CE,Pages_LM,Pages_QZ,Store,APIClient,FDeps frontend
  class Main,Router,Models,Service_CodeSub,Service_AI,Service_Exec,Service_Learn,Service_Quiz,DepBE backend
  class AIProvider,Sandbox,RootDeps external
  class StoreDB db
```
