# sm-daniyal/patternspecular architecture

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

- Interactive diagram: https://gitdiagram.com/sm-daniyal/patternspecular
- Repository: https://github.com/sm-daniyal/patternspecular

## Overview

Pattern Specular is a manager-facing writing analysis platform with a separate HR aggregate portal. Managers create or review job descriptions, interview feedback, and promotion writeups; the analysis engine flags and filters language, then returns evidence-backed observations. Longitudinal patterns and HR trends are separate downstream capabilities, alongside human review of proposed dictionary additions. The README documents these product stages and capabilities; sampled backend sources confirm the engine sequence and app wiring, while most frontend-to-backend connections remain unverified.

Main entry points: [`backend/src/pattern_specular/engine/orchestrator.py`](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/orchestrator.py) (Analysis orchestration), [`backend/src/pattern_specular/api/documents.py`](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/documents.py) (Writing workflows), [`backend/src/pattern_specular/main.py`](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/main.py) (API application), [`frontend/src/pages`](https://github.com/sm-daniyal/patternspecular/tree/main/frontend/src/pages) (Manager portal)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User surfaces"]
  node_manager_ui["Manager portal"]
  node_hr_ui["HR portal"]
end

subgraph group_api["API workflows"]
  node_app["API application<br/>[main.py]"]
  node_documents_api["Writing workflows<br/>[documents.py]"]
  node_auth_api["Authentication<br/>[auth.py]"]
  node_patterns_api["Pattern endpoints<br/>[patterns.py]"]
  node_hr_api["HR endpoints<br/>[hr.py]"]
  node_growth_api["Dictionary review API<br/>[growth.py]"]
end

subgraph group_engine["Analysis engine"]
  node_analysis["Analysis orchestration<br/>[orchestrator.py]"]
  node_dictionary["Dictionary matching<br/>[dictionary.py]"]
  node_context["Contextual pass<br/>[contextual_pass.py]"]
  node_adjudicator["Span adjudication<br/>[adjudicator.py]"]
  node_verdict["Statutory verdict<br/>[verdict.py]"]
  node_suppression["Dismissal suppression<br/>[suppression.py]"]
  node_judge["Consensus judge<br/>[judge.py]"]
  node_recommendations["Rewrite suggestions<br/>[recommendations.py]"]
  node_llm["Structured LLM client<br/>[llm_agent.py]"]
  node_drift["Criteria drift<br/>[drift.py]"]
end

subgraph group_insights["Insights and review"]
  node_patterns["Significance-gated patterns"]
  node_hr_trends["Aggregated HR trends<br/>[hr_aggregates.py]"]
  node_growth_review["Candidate debate and review"]
end

subgraph group_data["Identity and data"]
  node_database[("PostgreSQL data<br/>[session.py]")]
  node_documents["Documents and runs<br/>[documents.py]"]
  node_flags["Flags and responses<br/>[engine.py]"]
  node_identity["Users and subjects<br/>[identity.py]"]
  node_blob["Resume blob storage<br/>[blob_storage.py]"]
end

node_manager(("Manager"))
node_hr_user(("HR user"))

node_manager -->|"writes and reviews"| node_manager_ui
node_hr_user -->|"reviews aggregates"| node_hr_ui
node_manager_ui -.->|"submits writing"| node_documents_api
node_manager_ui -.->|"signs in"| node_auth_api
node_hr_ui -.->|"requests trends"| node_hr_api
node_hr_ui -.->|"reviews candidates"| node_growth_api
node_app -->|"routes"| node_documents_api
node_app -->|"routes"| node_auth_api
node_app -->|"routes"| node_patterns_api
node_app -->|"routes"| node_hr_api
node_app -->|"routes"| node_growth_api
node_documents_api -.->|"invokes analysis"| node_analysis
node_analysis -->|"runs first"| node_dictionary
node_analysis -->|"runs next"| node_context
node_analysis -->|"verifies spans"| node_adjudicator
node_analysis -->|"applies rulings"| node_verdict
node_analysis -->|"filters dismissals"| node_suppression
node_analysis -->|"scores consensus"| node_judge
node_analysis -->|"generates rewrites"| node_recommendations
node_analysis -.->|"checks criteria"| node_drift
node_context -->|"calls"| node_llm
node_growth_review -->|"uses agents"| node_llm
node_documents_api -->|"reads and writes"| node_documents
node_analysis -->|"persists flags"| node_flags
node_patterns_api -.->|"serves patterns"| node_patterns
node_hr_api -.->|"serves aggregates"| node_hr_trends
node_growth_api -.->|"handles review"| node_growth_review
node_auth_api -->|"authenticates users"| node_identity
node_documents_api -->|"uses sessions"| node_database
node_database -.->|"stores records"| node_documents
node_database -.->|"stores identities"| node_identity
node_documents -->|"relates analysis"| node_flags
node_identity -->|"owns documents"| node_documents
node_manager_ui -.->|"reviews drift"| node_drift
node_manager_ui -.->|"views patterns"| node_patterns_api
node_documents_api -.->|"serves resumes"| node_blob

click node_manager_ui "https://github.com/sm-daniyal/patternspecular/tree/main/frontend/src/pages"
click node_app "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/main.py"
click node_documents_api "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/documents.py"
click node_auth_api "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/auth.py"
click node_patterns_api "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/patterns.py"
click node_hr_api "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/hr.py"
click node_growth_api "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/growth.py"
click node_analysis "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/orchestrator.py"
click node_dictionary "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/dictionary.py"
click node_context "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/contextual_pass.py"
click node_adjudicator "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/adjudicator.py"
click node_verdict "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/verdict.py"
click node_suppression "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/suppression.py"
click node_judge "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/judge.py"
click node_recommendations "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/recommendations.py"
click node_llm "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/llm_agent.py"
click node_drift "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/drift.py"
click node_patterns "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/services/pattern_aggregator.py"
click node_hr_trends "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/services/hr_aggregates.py"
click node_growth_review "https://github.com/sm-daniyal/patternspecular/tree/main/backend/src/pattern_specular/engine/growth"
click node_database "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/db/session.py"
click node_documents "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/models/documents.py"
click node_flags "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/models/engine.py"
click node_identity "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/models/identity.py"
click node_blob "https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/services/blob_storage.py"

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_manager_ui,node_hr_ui,node_hr_user toneBlue
class node_app,node_documents_api,node_auth_api,node_patterns_api,node_hr_api,node_growth_api toneAmber
class node_analysis,node_dictionary,node_context,node_adjudicator,node_verdict,node_suppression,node_judge,node_recommendations,node_llm,node_drift toneMint
class node_patterns,node_hr_trends,node_growth_review toneRose
class node_database,node_documents,node_flags,node_identity,node_blob,node_manager toneIndigo
```

## Components

### User surfaces

- [Manager portal](https://github.com/sm-daniyal/patternspecular/tree/main/frontend/src/pages): `frontend/src/pages`
- **HR portal**

### API workflows

- [API application](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/main.py): `backend/src/pattern_specular/main.py`
- [Writing workflows](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/documents.py): `backend/src/pattern_specular/api/documents.py`
- [Authentication](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/auth.py): `backend/src/pattern_specular/api/auth.py`
- [Pattern endpoints](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/patterns.py): `backend/src/pattern_specular/api/patterns.py`
- [HR endpoints](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/hr.py): `backend/src/pattern_specular/api/hr.py`
- [Dictionary review API](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/api/growth.py): `backend/src/pattern_specular/api/growth.py`

### Analysis engine

- [Analysis orchestration](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/orchestrator.py): `backend/src/pattern_specular/engine/orchestrator.py`
- [Dictionary matching](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/dictionary.py): `backend/src/pattern_specular/engine/dictionary.py`
- [Contextual pass](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/contextual_pass.py): `backend/src/pattern_specular/engine/contextual_pass.py`
- [Span adjudication](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/adjudicator.py): `backend/src/pattern_specular/engine/adjudicator.py`
- [Statutory verdict](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/verdict.py): `backend/src/pattern_specular/engine/verdict.py`
- [Dismissal suppression](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/suppression.py): `backend/src/pattern_specular/engine/suppression.py`
- [Consensus judge](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/judge.py): `backend/src/pattern_specular/engine/judge.py`
- [Rewrite suggestions](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/recommendations.py): `backend/src/pattern_specular/engine/recommendations.py`
- [Structured LLM client](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/llm_agent.py): `backend/src/pattern_specular/engine/llm_agent.py`
- [Criteria drift](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/engine/drift.py): `backend/src/pattern_specular/engine/drift.py`

### Insights and review

- [Significance-gated patterns](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/services/pattern_aggregator.py): `backend/src/pattern_specular/services/pattern_aggregator.py`
- [Aggregated HR trends](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/services/hr_aggregates.py): `backend/src/pattern_specular/services/hr_aggregates.py`
- [Candidate debate and review](https://github.com/sm-daniyal/patternspecular/tree/main/backend/src/pattern_specular/engine/growth): `backend/src/pattern_specular/engine/growth`

### Identity and data

- [PostgreSQL data](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/db/session.py): `backend/src/pattern_specular/db/session.py`
- [Documents and runs](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/models/documents.py): `backend/src/pattern_specular/models/documents.py`
- [Flags and responses](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/models/engine.py): `backend/src/pattern_specular/models/engine.py`
- [Users and subjects](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/models/identity.py): `backend/src/pattern_specular/models/identity.py`
- [Resume blob storage](https://github.com/sm-daniyal/patternspecular/blob/main/backend/src/pattern_specular/services/blob_storage.py): `backend/src/pattern_specular/services/blob_storage.py`

### Other components

- **Manager**
- **HR user**

## Connections

- Manager → Manager portal: writes and reviews
- HR user → HR portal: reviews aggregates
- Manager portal → Writing workflows: submits writing
- Manager portal → Authentication: signs in
- HR portal → HR endpoints: requests trends
- HR portal → Dictionary review API: reviews candidates
- API application → Writing workflows: routes (evidence: `backend/src/pattern_specular/main.py`)
- API application → Authentication: routes (evidence: `backend/src/pattern_specular/main.py`)
- API application → Pattern endpoints: routes (evidence: `backend/src/pattern_specular/main.py`)
- API application → HR endpoints: routes (evidence: `backend/src/pattern_specular/main.py`)
- API application → Dictionary review API: routes (evidence: `backend/src/pattern_specular/main.py`)
- Writing workflows → Analysis orchestration: invokes analysis
- Analysis orchestration → Dictionary matching: runs first (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Analysis orchestration → Contextual pass: runs next (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Analysis orchestration → Span adjudication: verifies spans (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Analysis orchestration → Statutory verdict: applies rulings (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Analysis orchestration → Dismissal suppression: filters dismissals (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Analysis orchestration → Consensus judge: scores consensus (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Analysis orchestration → Rewrite suggestions: generates rewrites (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Analysis orchestration → Criteria drift: checks criteria (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Contextual pass → Structured LLM client: calls (evidence: `backend/src/pattern_specular/engine/contextual_pass.py`)
- Candidate debate and review → Structured LLM client: uses agents (evidence: `backend/src/pattern_specular/engine/growth/agents.py`)
- Writing workflows → Documents and runs: reads and writes (evidence: `backend/src/pattern_specular/api/documents.py`)
- Analysis orchestration → Flags and responses: persists flags (evidence: `backend/src/pattern_specular/engine/orchestrator.py`)
- Pattern endpoints → Significance-gated patterns: serves patterns
- HR endpoints → Aggregated HR trends: serves aggregates
- Dictionary review API → Candidate debate and review: handles review
- Authentication → Users and subjects: authenticates users (evidence: `backend/src/pattern_specular/api/auth.py`)
- Writing workflows → PostgreSQL data: uses sessions (evidence: `backend/src/pattern_specular/api/documents.py`)
- PostgreSQL data → Documents and runs: stores records
- PostgreSQL data → Users and subjects: stores identities
- Documents and runs → Flags and responses: relates analysis (evidence: `backend/src/pattern_specular/models/documents.py`)
- Users and subjects → Documents and runs: owns documents (evidence: `backend/src/pattern_specular/models/identity.py`)
- Manager portal → Criteria drift: reviews drift
- Manager portal → Pattern endpoints: views patterns
- Writing workflows → Resume blob storage: serves resumes
