PlanOpticon

planopticon / docs / architecture / overview.md

Source Rendered

Blame History Raw 146 lines

1	`# Architecture Overview`
2
3	`## System diagram`
4
5	```mermaid
6	`graph TD`
7	`subgraph Sources`
8	`S1[Video Files]`
9	`S2[Google Workspace]`
10	`S3[Microsoft 365]`
11	`S4[Zoom / Teams / Meet]`
12	`S5[YouTube]`
13	`S6[Notes — Obsidian / Notion / Apple Notes]`
14	`S7[GitHub]`
15	`end`
16
17	`subgraph Source Connectors`
18	`SC[Source Connectors + OAuth]`
19	`end`
20
21	`S1 --> SC`
22	`S2 --> SC`
23	`S3 --> SC`
24	`S4 --> SC`
25	`S5 --> SC`
26	`S6 --> SC`
27	`S7 --> SC`
28
29	`SC --> A[Ingest / Analyze Pipeline]`
30
31	`A --> B[Frame Extractor]`
32	`A --> C[Audio Extractor]`
33	`B --> D[Diagram Analyzer]`
34	`C --> E[Transcription]`
35	`D --> F[Knowledge Graph]`
36	`E --> F`
37	`E --> G[Key Point Extractor]`
38	`E --> H[Action Item Detector]`
39	`D --> I[Content Analyzer]`
40	`E --> I`
41
42	`subgraph Agent & Skills`
43	`AG[Planning Agent]`
44	`SK[Skill Registry]`
45	`CO[Companion REPL]`
46	`end`
47
48	`F --> AG`
49	`G --> AG`
50	`H --> AG`
51	`I --> AG`
52	`AG --> SK`
53	`F --> CO`
54
55	`F --> J[Plan Generator]`
56	`G --> J`
57	`H --> J`
58	`I --> J`
59
60	`subgraph Output & Export`
61	`J --> K[Markdown Report]`
62	`J --> L[HTML Report]`
63	`J --> M[PDF Report]`
64	`D --> N[Mermaid/SVG/PNG Export]`
65	`EX[Exporters — Obsidian / Notion / Exchange / Wiki]`
66	`end`
67
68	`AG --> EX`
69	`F --> EX`
70	```
71
72	`## Module structure`
73
74	```
75	`video_processor/`
76	`├── cli/ # CLI commands (Click)`
77	`│ └── commands.py`
78	`├── sources/ # Source connectors`
79	`│ ├── gdrive.py # Google Drive`
80	`│ ├── gws.py # Google Workspace (Docs, Sheets, Slides, Meet)`
81	`│ ├── m365.py # Microsoft 365 (OneDrive, SharePoint, Teams)`
82	`│ ├── dropbox.py # Dropbox`
83	`│ ├── zoom.py # Zoom recordings`
84	`│ ├── youtube.py # YouTube videos`
85	`│ ├── notion.py # Notion pages`
86	`│ ├── github.py # GitHub repos / wikis`
87	`│ ├── obsidian.py # Obsidian vaults`
88	`│ └── apple_notes.py # Apple Notes (macOS)`
89	`├── extractors/ # Media extraction`
90	`│ ├── frame_extractor.py # Video → frames`
91	`│ └── audio_extractor.py # Video → WAV`
92	`├── analyzers/ # AI-powered analysis`
93	`│ ├── diagram_analyzer.py # Frame classification + extraction`
94	`│ ├── content_analyzer.py # Cross-referencing`
95	`│ └── action_detector.py # Action item detection`
96	`├── integrators/ # Knowledge assembly`
97	`│ ├── knowledge_graph.py # Entity/relationship graph`
98	`│ ├── graph_query.py # Query engine`
99	`│ └── plan_generator.py # Report generation`
100	`├── agent/ # Planning agent`
101	`│ ├── agent.py # Agent loop`
102	`│ ├── skills.py # Skill registry`
103	`│ └── companion.py # Companion REPL`
104	`├── exporters/ # Export formats`
105	`│ ├── markdown.py # Markdown export`
106	`│ ├── obsidian.py # Obsidian vault export`
107	`│ ├── notion.py # Notion export`
108	`│ ├── wiki.py # Wiki generation + push`
109	`│ └── exchange.py # PlanOpticon Exchange Format`
110	`├── providers/ # AI provider abstraction`
111	`│ ├── base.py # BaseProvider ABC`
112	`│ ├── openai_provider.py`
113	`│ ├── anthropic_provider.py`
114	`│ ├── gemini_provider.py`
115	`│ ├── ollama_provider.py # Local Ollama (offline)`
116	`│ ├── azure_provider.py # Azure OpenAI`
117	`│ ├── together_provider.py`
118	`│ ├── fireworks_provider.py`
119	`│ ├── cerebras_provider.py`
120	`│ ├── xai_provider.py # xAI / Grok`
121	`│ ├── discovery.py # Auto-model-discovery`
122	`│ └── manager.py # ProviderManager routing`
123	`├── utils/`
124	`│ ├── json_parsing.py # Robust LLM JSON parsing`
125	`│ ├── rendering.py # Mermaid + chart rendering`
126	`│ ├── export.py # HTML/PDF export`
127	`│ ├── api_cache.py # Disk-based response cache`
128	`│ └── prompt_templates.py # LLM prompt management`
129	`├── auth.py # OAuth flow management`
130	`├── exchange.py # Exchange format schema`
131	`├── models.py # Pydantic data models`
132	`├── output_structure.py # Directory layout + manifest I/O`
133	`└── pipeline.py # Core processing pipeline`
134	```
135
136	`## Key design decisions`
137
138	`- Pydantic everywhere — All structured data uses pydantic models for validation and serialization`
139	- Manifest-driven — Every run produces `manifest.json` as the single source of truth
140	- Provider abstraction — Single `ProviderManager` wraps OpenAI, Anthropic, Gemini, Ollama, and additional providers behind a common interface
141	`- No hardcoded models — Model lists come from API discovery`
142	`- Screengrab fallback — When extraction fails, save the frame as a captioned screenshot`
143	- OAuth-first auth — All cloud service integrations use OAuth via `planopticon auth`, with credentials stored locally. Service account keys are supported as a fallback for server-side automation
144	`- Skill registry — The planning agent discovers and invokes skills dynamically. Skills are self-describing and can be composed by the agent to accomplish complex tasks`
145	- Exchange format — A portable JSON format (`exchange.py`) for importing and exporting knowledge graphs between PlanOpticon instances and external tools
146

PlanOpticon

Keyboard Shortcuts