# artasyaskar/opportunityos-ai architecture

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

- Interactive diagram: https://gitdiagram.com/artasyaskar/opportunityos-ai
- Repository: https://github.com/artasyaskar/opportunityos-ai

## Overview

OpportunityOS AI helps users discover and rank global opportunities, build an evidence-backed profile, and prepare tailored applications. The principal workflow runs from profile and document preparation through explainable matching to application drafting and pipeline tracking. The README documents broader research-memory and multi-provider AI capabilities; the sampled sources confirm evidence extraction and AI routing usage, but do not expose every route-to-service connection, so uncertain wiring is omitted.

Main entry points: [`src/services/ai/router.ts`](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/services/ai/router.ts) (AI provider router), [`src/app/dashboard/vault/page.tsx`](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/vault/page.tsx) (Knowledge vault), [`src/app/dashboard/opportunities/[id]/workspace/page.tsx`](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/opportunities/%5Bid%5D/workspace/page.tsx) (Opportunity workspace), [`src/lib/services/providers/IngestionPipeline.ts`](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/providers/IngestionPipeline.ts) (Opportunity ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Opportunity discovery"]
  node_dashboard["Opportunity dashboard<br/>[page.tsx]"]
  node_opportunity_catalog["Opportunity catalog<br/>[page.tsx]"]
  node_ingestion["Opportunity ingestion"]
  node_provider_registry["Provider registry"]
  node_recommendations["Personalized ranking"]
  node_ranking["Ranking service<br/>[RankingService.ts]"]
  node_scoring["Compatibility scoring<br/>[scoringEngine.ts]"]
end

subgraph group_profile["Profile and evidence"]
  node_onboarding["Profile onboarding<br/>[page.tsx]"]
  node_profile_api["Profile analysis<br/>[route.ts]"]
  node_document_api["Document intake<br/>[route.ts]"]
  node_vault["Knowledge vault<br/>[page.tsx]"]
  node_storage["Document storage<br/>[StorageManager.ts]"]
  node_evidence["Evidence extraction<br/>[EvidenceEngine.ts]"]
  node_canonical_profile["Canonical profile"]
end

subgraph group_applications["Application workflow"]
  node_workspace["Opportunity workspace<br/>[page.tsx]"]
  node_agent_api["Application agent APIs"]
  node_builder["Application builder"]
  node_evidence_review["Evidence review<br/>[EvidenceReview.tsx]"]
  node_pipeline_ui["Application pipeline"]
  node_pipeline_service["Pipeline service<br/>[PipelineService.ts]"]
  node_pipeline_store[("Pipeline records")]
end

subgraph group_platform["AI and platform services"]
  node_ai_router["AI provider router<br/>[router.ts]"]
end

node_user(("Student or professional"))
node_gemini["Gemini"]
node_groq["Groq"]
node_openrouter["OpenRouter vision"]
node_firebase_storage[("Firebase Storage")]

node_user -->|"explores"| node_dashboard
node_user -->|"browses"| node_opportunity_catalog
node_ingestion -->|"selects providers"| node_provider_registry
node_ingestion -.->|"supplies opportunities"| node_recommendations
node_recommendations -->|"ranks opportunities"| node_ranking
node_ranking -->|"scores compatibility"| node_scoring
node_user -->|"creates profile"| node_onboarding
node_onboarding -.->|"submits profile"| node_profile_api
node_user -->|"uploads documents"| node_document_api
node_document_api -.->|"adds documents"| node_vault
node_vault -.->|"manages files"| node_storage
node_storage -->|"stores files"| node_firebase_storage
node_vault -.->|"provides documents"| node_evidence
node_evidence -->|"extracts verified facts"| node_canonical_profile
node_user -->|"prepares application"| node_workspace
node_workspace -.->|"requests assistance"| node_agent_api
node_agent_api -.->|"dispatches task"| node_builder
node_builder -->|"generates draft"| node_ai_router
node_ai_router -.->|"routes request"| node_gemini
node_ai_router -.->|"fails over"| node_groq
node_ai_router -.->|"routes vision"| node_openrouter
node_workspace -.->|"reviews evidence"| node_evidence_review
node_user -->|"tracks applications"| node_pipeline_ui
node_pipeline_ui -->|"loads and saves"| node_pipeline_service
node_pipeline_service -->|"reads and writes"| node_pipeline_store

click node_dashboard "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/page.tsx"
click node_opportunity_catalog "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/opportunities/page.tsx"
click node_ingestion "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/providers/IngestionPipeline.ts"
click node_provider_registry "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/providers/providerRegistry.ts"
click node_recommendations "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/recommendationEngine.ts"
click node_ranking "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/RankingService.ts"
click node_scoring "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/scoringEngine.ts"
click node_onboarding "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/onboarding/page.tsx"
click node_profile_api "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/api/profile/analyze/route.ts"
click node_document_api "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/api/documents/parse/route.ts"
click node_vault "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/vault/page.tsx"
click node_storage "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/storage/StorageManager.ts"
click node_evidence "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/EvidenceEngine.ts"
click node_canonical_profile "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/ProfileMergeEngine.ts"
click node_workspace "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/opportunities/%5Bid%5D/workspace/page.tsx"
click node_agent_api "https://github.com/artasyaskar/opportunityos-ai/tree/main/src/app/api/agents"
click node_builder "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/services/ai/agents/applicationBuilderAgent.ts"
click node_evidence_review "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/components/EvidenceReview.tsx"
click node_pipeline_ui "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/components/auth/PipelineContext.tsx"
click node_pipeline_service "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/PipelineService.ts"
click node_pipeline_store "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/repositories/PipelineRepository.ts"
click node_ai_router "https://github.com/artasyaskar/opportunityos-ai/blob/main/src/services/ai/router.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_dashboard,node_opportunity_catalog,node_ingestion,node_provider_registry,node_recommendations,node_ranking,node_scoring toneBlue
class node_onboarding,node_profile_api,node_document_api,node_vault,node_storage,node_evidence,node_canonical_profile,node_firebase_storage toneAmber
class node_workspace,node_agent_api,node_builder,node_evidence_review,node_pipeline_ui,node_pipeline_service,node_pipeline_store,node_openrouter toneMint
class node_ai_router toneRose
class node_user,node_gemini,node_groq toneIndigo
```

## Components

### Opportunity discovery

- [Opportunity dashboard](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Opportunity catalog](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/opportunities/page.tsx): `src/app/opportunities/page.tsx`
- [Opportunity ingestion](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/providers/IngestionPipeline.ts): `src/lib/services/providers/IngestionPipeline.ts`
- [Provider registry](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/providers/providerRegistry.ts): `src/lib/services/providers/providerRegistry.ts`
- [Personalized ranking](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/recommendationEngine.ts): `src/lib/recommendationEngine.ts`
- [Ranking service](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/RankingService.ts): `src/lib/services/RankingService.ts`
- [Compatibility scoring](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/scoringEngine.ts): `src/lib/scoringEngine.ts`

### Profile and evidence

- [Profile onboarding](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/onboarding/page.tsx): `src/app/onboarding/page.tsx`
- [Profile analysis](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/api/profile/analyze/route.ts): `src/app/api/profile/analyze/route.ts`
- [Document intake](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/api/documents/parse/route.ts): `src/app/api/documents/parse/route.ts`
- [Knowledge vault](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/vault/page.tsx): `src/app/dashboard/vault/page.tsx`
- [Document storage](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/storage/StorageManager.ts): `src/lib/storage/StorageManager.ts`
- [Evidence extraction](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/EvidenceEngine.ts): `src/lib/services/EvidenceEngine.ts`
- [Canonical profile](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/ProfileMergeEngine.ts): `src/lib/services/ProfileMergeEngine.ts`

### Application workflow

- [Opportunity workspace](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/app/dashboard/opportunities/%5Bid%5D/workspace/page.tsx): `src/app/dashboard/opportunities/[id]/workspace/page.tsx`
- [Application agent APIs](https://github.com/artasyaskar/opportunityos-ai/tree/main/src/app/api/agents): `src/app/api/agents`
- [Application builder](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/services/ai/agents/applicationBuilderAgent.ts): `src/services/ai/agents/applicationBuilderAgent.ts`
- [Evidence review](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/components/EvidenceReview.tsx): `src/components/EvidenceReview.tsx`
- [Application pipeline](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/components/auth/PipelineContext.tsx): `src/components/auth/PipelineContext.tsx`
- [Pipeline service](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/services/PipelineService.ts): `src/lib/services/PipelineService.ts`
- [Pipeline records](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/lib/repositories/PipelineRepository.ts): `src/lib/repositories/PipelineRepository.ts`

### AI and platform services

- [AI provider router](https://github.com/artasyaskar/opportunityos-ai/blob/main/src/services/ai/router.ts): `src/services/ai/router.ts`

### Other components

- **Student or professional**
- **Gemini**
- **Groq**
- **OpenRouter vision**
- **Firebase Storage**

## Connections

- Student or professional → Opportunity dashboard: explores
- Student or professional → Opportunity catalog: browses
- Opportunity ingestion → Provider registry: selects providers
- Opportunity ingestion → Personalized ranking: supplies opportunities
- Personalized ranking → Ranking service: ranks opportunities
- Ranking service → Compatibility scoring: scores compatibility
- Student or professional → Profile onboarding: creates profile
- Profile onboarding → Profile analysis: submits profile
- Student or professional → Document intake: uploads documents
- Document intake → Knowledge vault: adds documents
- Knowledge vault → Document storage: manages files
- Document storage → Firebase Storage: stores files
- Knowledge vault → Evidence extraction: provides documents
- Evidence extraction → Canonical profile: extracts verified facts
- Student or professional → Opportunity workspace: prepares application
- Opportunity workspace → Application agent APIs: requests assistance
- Application agent APIs → Application builder: dispatches task
- Application builder → AI provider router: generates draft
- AI provider router → Gemini: routes request
- AI provider router → Groq: fails over
- AI provider router → OpenRouter vision: routes vision
- Opportunity workspace → Evidence review: reviews evidence
- Student or professional → Application pipeline: tracks applications
- Application pipeline → Pipeline service: loads and saves
- Pipeline service → Pipeline records: reads and writes