# jeffrey-p-mcateer/house architecture

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

- Interactive diagram: https://gitdiagram.com/jeffrey-p-mcateer/house
- Repository: https://github.com/jeffrey-p-mcateer/house

## Overview

##### Project type and purpose
- This is a single‐binary, text‐based adventure server (monolithic game engine) written in Java (with one C module), delivering an interactive house exploration game via TCP on port 8888. Clients connect with a generic TCP client (e.g. socat or telnet).

##### Analysis of the file structure
- Top‐level code files:
- Action.java, Item.java, InventoryItem.java – basic domain model for commands and items
- Guest.java – represents a connected player
- House.java, Room.java, *.room – in‐memory model and room definitions (plain text maps)
- Data.java, Util.java, E.java – persistence helpers, utilities, error handling
- Room.c – low‐level helper (e.g. performance‐critical room parser)
- build.sh – compiles Java & C, outputs .class files into the classes/ directory
- .room files (basement.room, kitchen.room, etc.) – static resources defining room layout
- readme.md – explains installation, runtime, and where persistent data lives (~/housemem)

##### Insights from the README
- The server is launched by build.sh
- Listens on TCP port 8888; clients connect via socat
- Game state is persisted under the user’s home directory in ~/housemem

##### Elements
- Annotation of ports (8888) and file paths (~/housemem, /path/to/*.room)

## Diagram (Mermaid)

```mermaid
flowchart TD
    client["TCP Client (socat/telnet)"]:::external
    client -->|"connects over TCP:8888"| tcpListener

    subgraph "Server Monolith"
        direction TB
        tcpListener["TCP Listener\n(port 8888)"]:::io
        parser["Command Parser & Dispatcher"]:::parser
        engineCore["Engine Core\n(game loop & state transitions)"]:::engine
        subgraph "Domain Model"
            House["House.java"]:::engine
            Room["Room.java"]:::engine
            Item["Item.java"]:::engine
            InventoryItem["InventoryItem.java"]:::engine
            Guest["Guest.java"]:::engine
        end
        persistence["Persistence Layer\n(~/housemem)"]:::persistence
        native["Native Helper\n(Room.c)"]:::native
        resources["Static Room Definitions\n(*.room)"]:::resource
        buildScript["build.sh"]:::build
        classesDir["classes/"]:::build
        readme["readme.md"]:::doc
    end

    tcpListener -->|"player input"| parser
    parser -->|"dispatch Action"| engineCore
    engineCore -->|"manipulates model"| House
    engineCore -->|"manipulates model"| Room
    engineCore -->|"manipulates model"| Item
    engineCore -->|"manipulates model"| InventoryItem
    engineCore -->|"manipulates model"| Guest
    engineCore -->|"save/load state"| persistence
    engineCore -->|"calls native parsing"| native
    resources -->|"room data loaded"| native
    native -->|"parsed room data"| engineCore
    engineCore -->|"response"| tcpListener

    buildScript -->|"compiles Java & C"| classesDir
    readme -.->|"docs & config"| buildScript

    click parser "https://github.com/jeffrey-p-mcateer/house/blob/master/Action.java"
    click parser "https://github.com/jeffrey-p-mcateer/house/blob/master/Util.java"
    click House "https://github.com/jeffrey-p-mcateer/house/blob/master/House.java"
    click Room "https://github.com/jeffrey-p-mcateer/house/blob/master/Room.java"
    click Item "https://github.com/jeffrey-p-mcateer/house/blob/master/Item.java"
    click InventoryItem "https://github.com/jeffrey-p-mcateer/house/blob/master/InventoryItem.java"
    click Guest "https://github.com/jeffrey-p-mcateer/house/blob/master/Guest.java"
    click persistence "https://github.com/jeffrey-p-mcateer/house/blob/master/Data.java"
    click native "https://github.com/jeffrey-p-mcateer/house/blob/master/Room.c"
    click resources "https://github.com/jeffrey-p-mcateer/house/blob/master/*.room"
    click buildScript "https://github.com/jeffrey-p-mcateer/house/blob/master/build.sh"
    click classesDir "https://github.com/jeffrey-p-mcateer/house/tree/master/classes/"
    click readme "https://github.com/jeffrey-p-mcateer/house/blob/master/readme.md"

    classDef external fill:#D6E9FE,stroke:#2B6CB0,color:#2B6CB0,stroke-width:2px;
    classDef io fill:#E8F6EF,stroke:#2F855A,color:#2F855A,stroke-width:2px;
    classDef parser fill:#FFF7D6,stroke:#D69E2E,color:#D69E2E,stroke-width:2px;
    classDef engine fill:#F0EBFF,stroke:#6B46C1,color:#6B46C1,stroke-width:2px;
    classDef persistence fill:#FFE8E8,stroke:#C53030,color:#C53030,stroke-width:2px;
    classDef native fill:#E6FFFA,stroke:#2C7A7B,color:#2C7A7B,stroke-width:2px;
    classDef resource fill:#F0FFF4,stroke:#38A169,color:#38A169,stroke-width:2px;
    classDef build fill:#EDF2F7,stroke:#4A5568,color:#4A5568,stroke-width:2px;
    classDef doc fill:#FFFFF0,stroke:#B7791F,color:#B7791F,stroke-width:2px;
```
