rewrite entity relationships to be more general

expand roles to explain these relationships