# akashgupta-26/polarity architecture

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

- Interactive diagram: https://gitdiagram.com/akashgupta-26/polarity
- Repository: https://github.com/akashgupta-26/polarity

## Overview

##### Project Type and Purpose
- Polarity is a standalone, high-performance chess engine written in C/C++.
- It exposes (implicitly) a command-line or library interface (the “engine.cpp” entry point), and supports perft benchmarking (“perftValidate.cpp” + “perftSuite.txt”).

##### File Structure
Top-level files each map to one logical module:
- engine.cpp                – Main driver / search orchestration
- perftValidate.cpp        – Perft tester harness
- board.h                  – Bitboard representation & state management
- constants.h              – Global constants (e.g. piece codes, castling flags)
- precalculated_move_tables.h – Lookup tables for knight/king moves & magic-bitboard data
- moves.h                  – Pseudo-legal move generation logic
- search.h                 – Search routines (minimax, alpha-beta, quiescence, pruning)
- evaluate.h               – Tapered evaluation (PeSTO tables, piece-square tables, king safety)
- random.h                 – Utility for any randomized testing or hashing
- perftSuite.txt           – Perft positions & expected node counts

##### Extract Architectural Patterns
- Layered pipeline: Board State → Move Generation → Search (with perft & transposition) → Evaluation.
- Data‐driven tables (precalc_move_tables) feed Move Generation & Evaluation.
- Search uses recursive calls (stackful take-back) + transposition hash + ordering heuristics.

##### Main System Components

A. Interface / Entry Points
- CLI / UCI Handler (in engine.cpp)
- Perft Harness (in perftValidate.cpp)

B. Core Engine Modules
1. Board Manager
– Maintains 12 piece bitboards + occupancy bitboards + castling/en-passant/side flags
2. Move Generator
– Pawn pushes (bit shifts)
– Lookup (knight/king) & magic bitboards (bishop/rook/queen)
– Pseudo-legal moves only (legality deferred)
3. Search Controller
– Minimax with Alpha-Beta
– Iterative Deepening, Quiescence, Aspiration Windows
– Null-move pruning, Late-move reductions
– Move ordering: MVV-LVA, History, Killer, PV
– Transposition Table (hash table stored in memory)
4. Evaluation Engine
– Tapered PeSTO tables (middlegame/endgame weights)
– Piece-square tables
– Pawn structure masks, king safety, mop-up endgame heuristic

C. Data & Utilities
- Precomputed Tables (shared by Move Generator & Evaluation)
- Random / Hashing utilities (for transposition keys)

##### Relationships & Data Flow
- User input → Engine Entry Point
- Engine → Board Manager (initialize position)
- Board Manager → Move Generator (generate moves)
- Move Generator → Search Controller (branch & recurse)
- Search Controller ↔ Evaluation Engine (leaf evaluation calls)
- Search Controller ↔ Board Manager (makeMove / takeBack interactions)
- Search Controller ↔ Transposition Table (probe & store)
- Engine Entry Point → Perft Harness (on perft command) → Board Manager / Move Generator (benchmark)

##### Architectural Patterns & Principles
- Single Responsibility: each .h/.cpp pair implements one concern
- Layering: clear separation of state, generation, search, evaluation
- Data locality & performance: bitboards + precalc tables
- Modular design: can swap or extend search / eval heuristics

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces
    CLI["CLI / UCI Handler"]:::interface
    Perft["Perft Harness"]:::interface

    %% Core Engine Modules
    Board["Board Manager"]:::core
    MoveGen["Move Generator"]:::core
    Search["Search Controller"]:::core
    Eval["Evaluation Engine"]:::core

    %% Data & Utilities
    Tables["Precomputed Tables"]:::data
    Constants["Global Constants"]:::data
    Random["Random / Hashing Utilities"]:::data
    TT[(Transposition Table)]:::data
    Suite["perftSuite.txt"]:::data
    Build["Makefile"]:::data
    Doc["README.md"]:::data

    %% Flow
    CLI -->|"initialize position"| Board
    Board -->|"generateMoves()"| MoveGen
    MoveGen -->|"branch to search"| Search
    Search -->|"evaluate()"| Eval
    Search -->|"makeMove/takeBack"| Board
    Search -->|"probe/store"| TT
    TT --> Search
    CLI -->|"perft command"| Perft
    Perft -->|"init position"| Board
    Perft -->|"benchmark moves"| MoveGen

    Tables --> MoveGen
    Tables --> Eval
    Constants --> Board
    Constants --> MoveGen
    Constants --> Search
    Constants --> Eval
    Random --> Search

    %% Click Events
    click CLI "https://github.com/akashgupta-26/polarity/blob/main/engine.cpp"
    click Perft "https://github.com/akashgupta-26/polarity/blob/main/perftValidate.cpp"
    click Perft "https://github.com/akashgupta-26/polarity/blob/main/perft.h"
    click Suite "https://github.com/akashgupta-26/polarity/blob/main/perftSuite.txt"
    click Board "https://github.com/akashgupta-26/polarity/blob/main/board.h"
    click MoveGen "https://github.com/akashgupta-26/polarity/blob/main/moves.h"
    click Search "https://github.com/akashgupta-26/polarity/blob/main/search.h"
    click Eval "https://github.com/akashgupta-26/polarity/blob/main/evaluate.h"
    click Tables "https://github.com/akashgupta-26/polarity/blob/main/precalculated_move_tables.h"
    click Constants "https://github.com/akashgupta-26/polarity/blob/main/constants.h"
    click Random "https://github.com/akashgupta-26/polarity/blob/main/random.h"
    click Build "https://github.com/akashgupta-26/polarity/tree/main/makefile"
    click Doc "https://github.com/akashgupta-26/polarity/blob/main/README.md"

    %% Styles
    classDef core fill:#cfe2ff,stroke:#0b5394,stroke-width:1px
    classDef data fill:#d9ead3,stroke:#38761d,stroke-width:1px
    classDef interface fill:#f9cb9c,stroke:#e69138,stroke-width:1px
```
