# zgdsaid1/emora architecture

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

- Interactive diagram: https://gitdiagram.com/zgdsaid1/emora
- Repository: https://github.com/zgdsaid1/emora

## Overview

HYBRID EMOTIONAL ENGINE is a Next.js product API and a framework-independent emotional-modeling core, with a separate evaluation package. The primary workflow authenticates a user, scopes requests to a project/profile, accepts a transition, computes a deterministic next state, and persists it for later retrieval. Other documented capabilities include workspace bootstrap, project/profile discovery and creation, transition history, and evaluation methodologies. Several evaluation and UI paths are present in the tree but were not sampled; their internal wiring is therefore omitted.

Main entry points: [`packages/database/src/schema/tables.ts`](https://github.com/zgdsaid1/emora/blob/main/packages/database/src/schema/tables.ts) (PostgreSQL Persistence), [`apps/web/app/api/v1/projects/[projectId]/profiles/[profileId]/transitions/route.ts`](https://github.com/zgdsaid1/emora/blob/main/apps/web/app/api/v1/projects/%5BprojectId%5D/profiles/%5BprofileId%5D/transitions/route.ts) (Transition API), [`apps/web/server/transitions/service.ts`](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/transitions/service.ts) (Transition Processing), [`packages/emotional-core/src/dynamics/calculate-next-state.ts`](https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/dynamics/calculate-next-state.ts) (Deterministic Dynamics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Product API"]
  node_bootstrap["Workspace Bootstrap<br/>[service.ts]"]
  node_project_discovery["Project Discovery<br/>[service.ts]"]
  node_profiles["Profile Management<br/>[service.ts]"]
  node_transition_api["Transition API<br/>[route.ts]"]
  node_transition_service["Transition Processing<br/>[service.ts]"]
  node_state_latest["Latest State<br/>[service.ts]"]
  node_state_history["State History<br/>[service.ts]"]
  node_transition_history["Transition History<br/>[service.ts]"]
end

subgraph group_authdata["Access and Persistence"]
  node_auth["Authentication and Authorization<br/>[authorization.ts]"]
  node_database[("PostgreSQL Persistence<br/>[tables.ts]")]
end

subgraph group_core["Emotional Model"]
  node_domain_mapping["Domain Mapping<br/>[domain-mapping.ts]"]
  node_dynamics["Deterministic Dynamics"]
  node_domain_types["Emotional Domain Types<br/>[emotional-state.ts]"]
  node_model_parameters["Model Parameters"]
  node_vector_math["Emotion Vectors<br/>[emotion-vector.ts]"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluation_contracts["Evaluation Contracts<br/>[contracts.ts]"]
  node_d09["D09 Evaluation<br/>[contracts.ts]"]
  node_d10["D10 Thresholds<br/>[threshold.ts]"]
  node_d11["D11 Methodology<br/>[methodology.ts]"]
  node_human_methodology["Human Methodology<br/>[contracts.ts]"]
end

node_user(("User"))

node_user -->|"bootstraps workspace"| node_bootstrap
node_user -->|"discovers projects"| node_project_discovery
node_user -->|"manages profiles"| node_profiles
node_user -->|"submits transition"| node_transition_api
node_transition_api -->|"runs transition"| node_transition_service
node_transition_api -->|"reads history"| node_transition_history
node_user -->|"requests latest state"| node_state_latest
node_user -->|"requests history"| node_state_history
node_transition_api -->|"authenticates request"| node_auth
node_bootstrap -->|"persists workspace"| node_database
node_profiles -->|"reads and writes"| node_database
node_profiles -->|"creates profile"| node_domain_types
node_transition_service -->|"reads and writes"| node_database
node_transition_service -->|"uses model core"| node_dynamics
node_transition_service -->|"maps state"| node_domain_mapping
node_state_latest -->|"reads state"| node_database
node_state_latest -->|"maps stored state"| node_domain_mapping
node_state_history -->|"reads history"| node_database
node_state_history -->|"maps stored state"| node_domain_mapping
node_transition_history -.->|"reads history"| node_database
node_dynamics -->|"validates state inputs"| node_domain_types
node_dynamics -->|"validates parameters"| node_model_parameters
node_dynamics -->|"calculates vectors"| node_vector_math
node_d09 -->|"references contracts"| node_human_methodology
node_d10 -->|"uses contracts"| node_d09
node_d10 -->|"canonicalizes inputs"| node_evaluation_contracts
node_d11 -->|"uses contracts"| node_d09
node_d11 -->|"canonicalizes inputs"| node_evaluation_contracts

click node_bootstrap "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/bootstrap/service.ts"
click node_project_discovery "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/profiles/service.ts"
click node_profiles "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/profiles/service.ts"
click node_transition_api "https://github.com/zgdsaid1/emora/blob/main/apps/web/app/api/v1/projects/%5BprojectId%5D/profiles/%5BprofileId%5D/transitions/route.ts"
click node_transition_service "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/transitions/service.ts"
click node_state_latest "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/states/service.ts"
click node_state_history "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/states/history/service.ts"
click node_transition_history "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/transitions/history/service.ts"
click node_auth "https://github.com/zgdsaid1/emora/blob/main/packages/auth/src/authorization.ts"
click node_database "https://github.com/zgdsaid1/emora/blob/main/packages/database/src/schema/tables.ts"
click node_domain_mapping "https://github.com/zgdsaid1/emora/blob/main/apps/web/server/transitions/domain-mapping.ts"
click node_dynamics "https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/dynamics/calculate-next-state.ts"
click node_domain_types "https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/domain/emotional-state.ts"
click node_model_parameters "https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/parameters/model-parameters.ts"
click node_vector_math "https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/domain/emotion-vector.ts"
click node_evaluation_contracts "https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/contracts.ts"
click node_d09 "https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/d09/contracts.ts"
click node_d10 "https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/d10/threshold.ts"
click node_d11 "https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/d11/methodology.ts"
click node_human_methodology "https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/human-methodology/contracts.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_bootstrap,node_project_discovery,node_profiles,node_transition_api,node_transition_service,node_state_latest,node_state_history,node_transition_history,node_user toneBlue
class node_auth,node_database toneAmber
class node_domain_mapping,node_dynamics,node_domain_types,node_model_parameters,node_vector_math toneMint
class node_evaluation_contracts,node_d09,node_d10,node_d11,node_human_methodology toneRose
```

## Components

### Product API

- [Workspace Bootstrap](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/bootstrap/service.ts): `apps/web/server/bootstrap/service.ts`
- [Project Discovery](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/profiles/service.ts): `apps/web/server/profiles/service.ts`
- [Profile Management](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/profiles/service.ts): `apps/web/server/profiles/service.ts`
- [Transition API](https://github.com/zgdsaid1/emora/blob/main/apps/web/app/api/v1/projects/%5BprojectId%5D/profiles/%5BprofileId%5D/transitions/route.ts): `apps/web/app/api/v1/projects/[projectId]/profiles/[profileId]/transitions/route.ts`
- [Transition Processing](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/transitions/service.ts): `apps/web/server/transitions/service.ts`
- [Latest State](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/states/service.ts): `apps/web/server/states/service.ts`
- [State History](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/states/history/service.ts): `apps/web/server/states/history/service.ts`
- [Transition History](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/transitions/history/service.ts): `apps/web/server/transitions/history/service.ts`

### Access and Persistence

- [Authentication and Authorization](https://github.com/zgdsaid1/emora/blob/main/packages/auth/src/authorization.ts): `packages/auth/src/authorization.ts`
- [PostgreSQL Persistence](https://github.com/zgdsaid1/emora/blob/main/packages/database/src/schema/tables.ts): `packages/database/src/schema/tables.ts`

### Emotional Model

- [Domain Mapping](https://github.com/zgdsaid1/emora/blob/main/apps/web/server/transitions/domain-mapping.ts): `apps/web/server/transitions/domain-mapping.ts`
- [Deterministic Dynamics](https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/dynamics/calculate-next-state.ts): `packages/emotional-core/src/dynamics/calculate-next-state.ts`
- [Emotional Domain Types](https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/domain/emotional-state.ts): `packages/emotional-core/src/domain/emotional-state.ts`
- [Model Parameters](https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/parameters/model-parameters.ts): `packages/emotional-core/src/parameters/model-parameters.ts`
- [Emotion Vectors](https://github.com/zgdsaid1/emora/blob/main/packages/emotional-core/src/domain/emotion-vector.ts): `packages/emotional-core/src/domain/emotion-vector.ts`

### Evaluation

- [Evaluation Contracts](https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/contracts.ts): `packages/emora-evaluation/src/contracts.ts`
- [D09 Evaluation](https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/d09/contracts.ts): `packages/emora-evaluation/src/d09/contracts.ts`
- [D10 Thresholds](https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/d10/threshold.ts): `packages/emora-evaluation/src/d10/threshold.ts`
- [D11 Methodology](https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/d11/methodology.ts): `packages/emora-evaluation/src/d11/methodology.ts`
- [Human Methodology](https://github.com/zgdsaid1/emora/blob/main/packages/emora-evaluation/src/human-methodology/contracts.ts): `packages/emora-evaluation/src/human-methodology/contracts.ts`

### Other components

- **User**

## Connections

- User → Workspace Bootstrap: bootstraps workspace
- User → Project Discovery: discovers projects
- User → Profile Management: manages profiles
- User → Transition API: submits transition (evidence: `apps/web/app/api/v1/projects/[projectId]/profiles/[profileId]/transitions/route.ts`)
- Transition API → Transition Processing: runs transition (evidence: `apps/web/app/api/v1/projects/[projectId]/profiles/[profileId]/transitions/route.ts`)
- Transition API → Transition History: reads history (evidence: `apps/web/app/api/v1/projects/[projectId]/profiles/[profileId]/transitions/route.ts`)
- User → Latest State: requests latest state
- User → State History: requests history
- Transition API → Authentication and Authorization: authenticates request (evidence: `apps/web/app/api/v1/projects/[projectId]/profiles/[profileId]/transitions/route.ts`)
- Workspace Bootstrap → PostgreSQL Persistence: persists workspace (evidence: `apps/web/server/bootstrap/service.ts`)
- Profile Management → PostgreSQL Persistence: reads and writes (evidence: `apps/web/server/profiles/service.ts`)
- Profile Management → Emotional Domain Types: creates profile (evidence: `apps/web/server/profiles/service.ts`)
- Transition Processing → PostgreSQL Persistence: reads and writes (evidence: `apps/web/server/transitions/service.ts`)
- Transition Processing → Deterministic Dynamics: uses model core (evidence: `apps/web/server/transitions/service.ts`)
- Transition Processing → Domain Mapping: maps state (evidence: `apps/web/server/transitions/service.ts`)
- Latest State → PostgreSQL Persistence: reads state (evidence: `apps/web/server/states/service.ts`)
- Latest State → Domain Mapping: maps stored state (evidence: `apps/web/server/states/service.ts`)
- State History → PostgreSQL Persistence: reads history (evidence: `apps/web/server/states/history/service.ts`)
- State History → Domain Mapping: maps stored state (evidence: `apps/web/server/states/history/service.ts`)
- Transition History → PostgreSQL Persistence: reads history
- Deterministic Dynamics → Emotional Domain Types: validates state inputs (evidence: `packages/emotional-core/src/dynamics/calculate-next-state.ts`)
- Deterministic Dynamics → Model Parameters: validates parameters (evidence: `packages/emotional-core/src/dynamics/calculate-next-state.ts`)
- Deterministic Dynamics → Emotion Vectors: calculates vectors (evidence: `packages/emotional-core/src/dynamics/calculate-next-state.ts`)
- D09 Evaluation → Human Methodology: references contracts (evidence: `packages/emora-evaluation/src/d09/contracts.ts`)
- D10 Thresholds → D09 Evaluation: uses contracts (evidence: `packages/emora-evaluation/src/d10/threshold.ts`)
- D10 Thresholds → Evaluation Contracts: canonicalizes inputs (evidence: `packages/emora-evaluation/src/d10/threshold.ts`)
- D11 Methodology → D09 Evaluation: uses contracts (evidence: `packages/emora-evaluation/src/d11/methodology.ts`)
- D11 Methodology → Evaluation Contracts: canonicalizes inputs (evidence: `packages/emora-evaluation/src/d11/methodology.ts`)
