GitSyntropy Docs
Everything you need to use, understand, and extend GitSyntropy.
rocket_launch Quick Start
- 1
Connect GitHub
Click Sign In and authorise GitSyntropy's GitHub OAuth app. We request read-only access to your public profile and commit history.
- 2
Sync your GitHub signals
On the Dashboard, enter your GitHub username and click Sync Signals. The GitHub Analyst agent will extract your commit patterns, PR cadence, and chronotype in the background.
- 3
Complete the Assessment
Navigate to Assessment and answer the 8-dimension psychometric questionnaire. Each question is a 1-5 slider between two behavioural extremes. This takes ~5 minutes.
- 4
Create or join a team
Go to Workspace → Create Team. Add team members by searching for their GitHub handle. Each member should also sign in and complete their own assessment.
- 5
Run the full analysis
From Insights or Dashboard, click Run Full Analysis. The LangGraph pipeline streams results live via WebSocket. When complete, a full narrative report is saved and accessible from Dashboard → Recent Reports.
account_tree Pipeline Overview
GitSyntropy uses a directed LangGraph state machine with four nodes running sequentially. Each node reads from and writes to a shared OrchestratorState TypedDict.
START → github_analyst → psychometric_profiler → compatibility_engine → synthesis → END
github_analyst
Inputs
team_id, user_id, github_handle, access_token
Outputs
github_signals (chronotype, rhythm_score, collab_index, commit_count, pr_count)
Fallback
Falls back to cached DB GithubProfile, then to deterministic mock keyed on handle.
psychometric_profiler
Inputs
user_id, member_profiles
Outputs
assessment_profile (8 dimension scores, completeness flag)
Fallback
Uses neutral midpoint scores (all 3s) for unscored members.
compatibility_engine
Inputs
assessment_profile, member_profiles, github_signals
Outputs
compatibility (total_score_36, weak/strong dimensions, risk_flags, confidence)
Fallback
Single-user vs reference profile when fewer than 2 scored members.
synthesis
Inputs
compatibility, github_signals, assessment_profile
Outputs
synthesis_text (streamed Claude Sonnet narrative), synthesis (structured dict)
Fallback
Template-based fallback if Claude API is unavailable.
psychology Assessment Dimensions
The psychometric model uses 8 behavioural dimensions, each scored 1–5. Higher scores indicate the right-label extreme; lower scores indicate the left-label extreme.
| Dimension | Score 1 | Score 5 | Weight |
|---|---|---|---|
| Innovation Drive | Stability-focused | Exploration-first | 16.7% |
| Leadership Orientation | Collaborative execution | Decisive authority | 13.9% |
| Team Resilience | Controlled, steady pace | Adaptive under pressure | 13.9% |
| Work Style | Independent deep-work | Pair-programming preferred | 11.1% |
| Decision Style | Data-driven, slow | Intuitive, fast | 11.1% |
| Risk Tolerance | Risk-averse, methodical | High-velocity, accepts risk | 11.1% |
| Stress Response | Avoidance under stress | Confronts blockers directly | 11.1% |
| Chronotype Sync | Deep night work | Peak morning output | 11.1% |
analytics Compatibility Scoring
Score Range
Each dimension pair contributes up to its weight × 6 points (max score 36). The raw score is converted to a 0–100% resilience score for display. Level bands: Excellent (≥28), Good (22–27), Fair (16–21), Poor (<16).
Pairwise Aggregation
For teams with N members, all N×(N-1)/2 pairs are scored. Dimension scores are averaged across pairs. Weak dimensions are the union of all pairs' weak signals; strong dimensions require all pairs to be strong on that dimension.
Confidence & Data Gaps
Confidence is reduced when members are missing GitHub data or haven't completed the assessment. Data gaps are reported in the compatibility response so you can identify which members need to complete their profiles.
api API Reference
Base URL: https://gitsyntropy.onrender.com/api/v1
/health Health check — returns service status and version.
/auth/github/start Returns GitHub OAuth authorization URL.
/auth/github/callback Exchange GitHub code for JWT access token.
/users/me Get authenticated user's profile.
/users/me/display-name Update display name.
/users/search?q= Search users by GitHub handle or display name.
/github/sync Trigger GitHub behavioral data sync for a handle.
/github/sync/:sync_id Poll sync status.
/assessment/questions Fetch all psychometric questions.
/assessment/responses Submit assessment answers.
/compatibility/run Compute pairwise compatibility score.
/orchestrator/run Start a full LangGraph analysis run.
/ws/analysis/:run_id WebSocket stream for orchestrator progress events.
/insights/synthesis Fetch latest synthesis report.
/teams Create a new team.
/teams?user_id= List all teams for a user.
/teams/:id/members Add a member to a team.
/teams/:id/members/:uid Remove a member from a team.