How sm-daniyal/patternspecular works
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: orchestrator.py Analysis orchestration · documents.py Writing workflows · main.py API application · pages Manager portal
Components 28
User surfaces
- Manager portal
frontend/src/pages - HR portal
API workflows
- API application
backend/src/pattern_specular/main.py - Writing workflows
backend/src/pattern_specular/api/documents.py - Authentication
backend/src/pattern_specular/api/auth.py - Pattern endpoints
backend/src/pattern_specular/api/patterns.py - HR endpoints
backend/src/pattern_specular/api/hr.py - Dictionary review API
backend/src/pattern_specular/api/growth.py
Analysis engine
- Analysis orchestration
backend/src/pattern_specular/engine/orchestrator.py - Dictionary matching
backend/src/pattern_specular/engine/dictionary.py - Contextual pass
backend/src/pattern_specular/engine/contextual_pass.py - Span adjudication
backend/src/pattern_specular/engine/adjudicator.py - Statutory verdict
backend/src/pattern_specular/engine/verdict.py - Dismissal suppression
backend/src/pattern_specular/engine/suppression.py - Consensus judge
backend/src/pattern_specular/engine/judge.py - Rewrite suggestions
backend/src/pattern_specular/engine/recommendations.py - Structured LLM client
backend/src/pattern_specular/engine/llm_agent.py - Criteria drift
backend/src/pattern_specular/engine/drift.py
Insights and review
- Significance-gated patterns
backend/src/pattern_specular/services/pattern_aggregator.py - Aggregated HR trends
backend/src/pattern_specular/services/hr_aggregates.py - Candidate debate and review
backend/src/pattern_specular/engine/growth
Identity and data
- PostgreSQL data
backend/src/pattern_specular/db/session.py - Documents and runs
backend/src/pattern_specular/models/documents.py - Flags and responses
backend/src/pattern_specular/models/engine.py - Users and subjects
backend/src/pattern_specular/models/identity.py - Resume blob storage
backend/src/pattern_specular/services/blob_storage.py
Other components
- Manager
- HR user
Connections 36
- 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
backend/src/pattern_specular/main.py - API application → Authentication: routes
backend/src/pattern_specular/main.py - API application → Pattern endpoints: routes
backend/src/pattern_specular/main.py - API application → HR endpoints: routes
backend/src/pattern_specular/main.py - API application → Dictionary review API: routes
backend/src/pattern_specular/main.py - Writing workflows → Analysis orchestration: invokes analysis
- Analysis orchestration → Dictionary matching: runs first
backend/src/pattern_specular/engine/orchestrator.py - Analysis orchestration → Contextual pass: runs next
backend/src/pattern_specular/engine/orchestrator.py - Analysis orchestration → Span adjudication: verifies spans
backend/src/pattern_specular/engine/orchestrator.py - Analysis orchestration → Statutory verdict: applies rulings
backend/src/pattern_specular/engine/orchestrator.py - Analysis orchestration → Dismissal suppression: filters dismissals
backend/src/pattern_specular/engine/orchestrator.py - Analysis orchestration → Consensus judge: scores consensus
backend/src/pattern_specular/engine/orchestrator.py - Analysis orchestration → Rewrite suggestions: generates rewrites
backend/src/pattern_specular/engine/orchestrator.py - Analysis orchestration → Criteria drift: checks criteria
backend/src/pattern_specular/engine/orchestrator.py - Contextual pass → Structured LLM client: calls
backend/src/pattern_specular/engine/contextual_pass.py - Candidate debate and review → Structured LLM client: uses agents
backend/src/pattern_specular/engine/growth/agents.py - Writing workflows → Documents and runs: reads and writes
backend/src/pattern_specular/api/documents.py - Analysis orchestration → Flags and responses: persists flags
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
backend/src/pattern_specular/api/auth.py - Writing workflows → PostgreSQL data: uses sessions
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
backend/src/pattern_specular/models/documents.py - Users and subjects → Documents and runs: owns documents
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