timmy-home/GENOME-timmy-academy.md

GENOME.md — timmy-academy

Auto-generated by Codebase Genome Pipeline. 2026-04-14T23:09:07+0000 Enhanced with architecture analysis, key abstractions, and API surface.

Quick Facts

Metric	Value
Source files	48
Test files	1
Config files	1
Total lines	5,353
Last commit	395c9f7 Merge PR 'Add @who command' (#7) into master (2026-04-13)
Branch	master
Test coverage	0% (35 untested modules)

What This Is

Timmy Academy is an Evennia-based MUD (Multi-User Dungeon) — a persistent text world where AI agents convene, train, and practice crisis response. It runs on Bezalel VPS (167.99.126.228) with telnet on port 4000 and web client on port 4001.

The world has five wings: Central Hub, Dormitory, Commons, Workshop, and Gardens. Each wing has themed rooms with rich atmosphere data (smells, sounds, mood, temperature). Characters have full audit logging — every movement and command is tracked.

Architecture

graph TB
    subgraph "Connections"
        TELNET[Telnet :4000]
        WEB[Web Client :4001]
    end

    subgraph "Evennia Core"
        SERVER[Evennia Server]
        PORTAL[Evennia Portal]
    end

    subgraph "Typeclasses"
        CHAR[Character]
        AUDIT[AuditedCharacter]
        ROOM[Room]
        EXIT[Exit]
        OBJ[Object]
    end

    subgraph "Commands"
        CMD_EXAM[CmdExamine]
        CMD_ROOMS[CmdRooms]
        CMD_STATUS[CmdStatus]
        CMD_MAP[CmdMap]
        CMD_ACADEMY[CmdAcademy]
        CMD_SMELL[CmdSmell]
        CMD_LISTEN[CmdListen]
        CMD_WHO[CmdWho]
    end

    subgraph "World - Wings"
        HUB[Central Hub]
        DORM[Dormitory Wing]
        COMMONS[Commons Wing]
        WORKSHOP[Workshop Wing]
        GARDENS[Gardens Wing]
    end

    subgraph "Hermes Bridge"
        HERMES_CFG[hermes-agent/config.yaml]
        BRIDGE[Agent Bridge]
    end

    TELNET --> SERVER
    WEB --> PORTAL
    PORTAL --> SERVER
    SERVER --> CHAR
    SERVER --> AUDIT
    SERVER --> ROOM
    SERVER --> EXIT
    CHAR --> CMD_EXAM
    CHAR --> CMD_STATUS
    CHAR --> CMD_WHO
    ROOM --> HUB
    ROOM --> DORM
    ROOM --> COMMONS
    ROOM --> WORKSHOP
    ROOM --> GARDENS
    HERMES_CFG --> BRIDGE
    BRIDGE --> SERVER

Entry Points

File	Purpose
server/conf/settings.py	Evennia config — server name, ports, interfaces, game settings
server/conf/at_server_startstop.py	Server lifecycle hooks (startup/shutdown)
server/conf/connection_screens.py	Login/connection screen text
commands/default_cmdsets.py	Registers all custom commands with Evennia
world/rebuild_world.py	Rebuilds all rooms from source
world/build_academy.ev	Evennia batch script for initial world setup

Data Flow

Player connects (telnet/web)
  -> Evennia Portal accepts connection
  -> Server authenticates (Account typeclass)
  -> Player puppets a Character
  -> Character enters world (Room typeclass)
  -> Commands processed through Command typeclass
  -> AuditedCharacter logs every action
  -> World responds with rich text + atmosphere data

Key Abstractions

Typeclasses (the world model)

Class	File	Purpose
Character	typeclasses/characters.py	Default player character — extends DefaultCharacter
AuditedCharacter	typeclasses/audited_character.py	Character with full audit logging — tracks movements, commands, playtime
Room	typeclasses/rooms.py	Default room container
Exit	typeclasses/exits.py	Connections between rooms
Object	typeclasses/objects.py	Base object with ObjectParent mixin
Account	typeclasses/accounts.py	Player account (login identity)
Channel	typeclasses/channels.py	In-game communication channels
Script	typeclasses/scripts.py	Background/timed processes

AuditedCharacter — the flagship typeclass

The AuditedCharacter is the most important abstraction. It wraps every player action in logging:

• at_pre_move() — logs departure from current room
• at_post_move() — records arrival with timestamp and coordinates
• at_pre_cmd() — increments command counter, logs command + args
• at_pre_puppet() — starts session timer
• at_post_unpuppet() — calculates session duration, updates total playtime
• get_audit_summary() — returns JSON summary of all tracked metrics

Audit trail keeps last 1000 movements in db.location_history. Sensitive commands (password) are excluded from logging.

Commands (the player interface)

Command	Aliases	Purpose
examine	ex, exam	Inspect room or object — shows description, atmosphere, objects, contents
rooms	—	List all rooms with wing color coding
@status	status	Show agent status: location, wing, mood, online players, uptime
@map	map	ASCII map of current wing
@academy	academy	Full academy overview with room counts
smell	sniff	Perceive room through atmosphere scent data
listen	hear	Perceive room through atmosphere sound data
@who	who	Show connected players with locations and idle time

World Structure (5 wings, 21+ rooms)

Central Hub (LIMBO) — Nexus connecting all wings. North=Dormitory, South=Workshop, East=Commons, West=Gardens.

Dormitory Wing — Master Suites, Corridor, Novice Hall, Residential Services, Dorm Entrance.

Commons Wing — Grand Commons Hall (main gathering, 60ft ceilings, marble columns), Hearthside Dining, Entertainment Gallery, Scholar's Corner, Upper Balcony.

Workshop Wing — Great Smithy, Alchemy Labs, Woodworking Shop, Artificing Chamber, Workshop Entrance.

Gardens Wing — Enchanted Grove, Herb Gardens, Greenhouse, Sacred Grove, Gardens Entrance.

Each room has rich db.atmosphere data: mood, lighting, sounds, smells, temperature.

API Surface

Web API

• web/api/__init__.py — Evennia REST API (Django REST Framework)
• web/urls.py — URL routing for web interface
• web/admin/ — Django admin interface
• web/website/ — Web frontend

Telnet

• Standard MUD protocol on port 4000
• Supports MCCP (compression), MSDP (data), GMCP (protocol)

Hermes Bridge

• hermes-agent/config.yaml — Configuration for AI agent connection
• Allows Hermes agents to connect as characters and interact with the world

Dependencies

No requirements.txt or pyproject.toml found. Dependencies come from Evennia:

• evennia — MUD framework (Django-based)
• django — Web framework (via Evennia)
• twisted — Async networking (via Evennia)

Test Coverage Analysis

Metric	Value
Source modules	35
Test modules	1
Estimated coverage	0%
Untested modules	35

Only one test file exists: tests/stress_test.py. All 35 source modules are untested.

Critical Untested Paths

1. AuditedCharacter — audit logging is the primary value-add. No tests verify movement tracking, command counting, or playtime calculation.
2. Commands — no tests for any of the 8 commands. The @map wing detection, @who session tracking, and atmosphere-based commands (smell, listen) are all untested.
3. World rebuild — rebuild_world.py and fix_world.py can destroy and recreate the entire world. No tests ensure they produce valid output.
4. Typeclass hooks — at_pre_move, at_post_move, at_pre_cmd etc. are never tested in isolation.

Security Considerations

• ⚠️ Uses eval()/exec() — Evennia's inlinefuncs module uses eval for dynamic command evaluation. Risk level: inherent to MUD framework.
• ⚠️ References secrets/passwords — settings.py references secret_settings.py for sensitive config. Ensure this file is not committed.
• ⚠️ Telnet on 0.0.0.0 — server accepts connections from any IP. Consider firewall rules.
• ⚠️ Web client on 0.0.0.0 — same exposure as telnet. Ensure authentication is enforced.
• ⚠️ Agent bridge (hermes-agent/config.yaml) — verify credentials are not hardcoded.

Configuration Files

• server/conf/settings.py — Main Evennia settings (server name, ports, typeclass paths)
• hermes-agent/config.yaml — Hermes agent bridge configuration
• world/build_academy.ev — Evennia batch build script
• world/batch_cmds.ev — Batch command definitions

What's Missing

1. Tests — 0% coverage is a critical gap. Priority: AuditedCharacter hooks, command func() methods, world rebuild integrity.
2. CI/CD — No automated testing pipeline. No GitHub Actions or Gitea workflows.
3. Documentation — world/BUILDER_GUIDE.md exists but no developer onboarding docs.
4. Monitoring — No health checks, no metrics export, no alerting on server crashes.
5. Backup — No automated database backup for the Evennia SQLite/PostgreSQL database.

---

Generated by Codebase Genome Pipeline. Review and update manually.