better architecture + docs, maybe its time to gemify this