Oculus Rendering Architecture - Code Index

A practical index to the actual implementation

This document maps the rendering flow to actual code locations. Use it to find where things happen without diving too deep.

---

Entry Points (API Layer)

File: oculus-api/oculus/api.py

Endpoint	Line	Purpose
goto_node()	:695	Navigate to node, trigger rendering
peek_path()	:1558	Read value at path (level=clouds for rendered)
poke_path()	:1661	Write value at path

---

Fence Execution

File: oculus-api/oculus/fence_executor.py

Core Classes

Class	Line	Purpose
FenceExecutionContext	:67	Context passed to providers (slug, mode, registry, credentials, graph)
FenceProvider	:119	Base class for all providers

Key Methods

Method	Line	Purpose
execute_fence()	:650	Main entry - routes to provider based on fence_info
execute_fence_async()	:753	Non-blocking version with timeout
execute_fences_in_tokens()	:820	Execute all fences in a token stream
execute_fences_parallel()	:899	Parallel fence execution

Execution Flow (execute_fence :650-751)

1. Parse fence_info → FenceInfo object (:673-676)
2. Attach to context (:679)
3. Loop providers, find matching one (:695-708)
4. Call provider.execute() (:701 or :707)
5. Log execution event (:726-749)
6. Return result dict

---

Fence Providers

Directory: oculus-api/oculus/providers/

Provider	File	Handles
GraphNodeProvider	graphnode_provider.py:35	graphnode:slug:path
PythonProvider	python_provider.py:23	python[execute=true]
AWSProvider	aws_provider.py:22	aws:service:method
SSMParameterProvider	aws_provider.py:94	ssm:parameter
BashProvider	bash_provider.py:22	bash, sh
HTTPProvider	http_provider.py:20	http:get, http:post
SQLiteProvider	sqlite_provider.py:21	sql:query
PostgresProvider	postgres_provider.py:19	postgres:query
StaticDataProvider	static_data_provider.py:27	yaml, json, toml
JMESPathProvider	jmespath_provider.py:21	jmespath
SymlinkProvider	symlink_provider.py:22	symlink:/path
RubyProvider	ruby_provider.py:35	ruby
SteampipeProvider	steampipe_provider.py:20	steampipe:resource
JenkinsPipelineProvider	jenkins_provider.py:21	jenkins:pipeline

---

Middleware Pipeline

File: oculus-api/oculus/middleware.py

Core Classes

Class	Line	Purpose
Middleware	:43	Base class with accepts/produces/terminal
MiddlewarePipeline	:121	Chains middleware, runs in order

Implemented Middleware

Middleware	Line	Purpose
DatetimeNormalizer	:238	Convert datetime → ISO strings
TableExtractor	:263	Project nested JSON into tables
AWSResponseCleaner	:512	Strip AWS ResponseMetadata
XMLParser	:534	Parse XML strings to dict
FortuneFormatter	:683	Format fortune quotes
AGAIMarkdownFormatter	:758	AGAI-specific formatting
CodeWindowFormatter	:855	Syntax-highlighted code blocks
SingleObjectFormatter	:939	Vertical key-value tables
YAMLTableNormalizer	:1015	Normalize YAML for SQL
TemplateRenderer	:1140	Jinja2 template application
DataMiddleware	:1255	Declarative slicing/sorting
FilterMiddleware	:1320	JMESPath-based filtering
AggregateMiddleware	:1439	Statistical aggregations
TransformMiddleware	:1584	JMESPath transformation
EmitMiddleware	:1621	Final output stage
VariableInterpolatorMiddleware	:1767	${...} substitution
IncludeExpanderMiddleware	:1828	{{...}} includes
FenceExecutorMiddleware	:1892	Execute fences in pipeline
CachingMiddleware	:1989	Cache fence results

Pipeline Flow

data_in → [should_run check] → process(data, context) → data_out
                                        ↓
                               [next middleware...]
                                        ↓
                               [terminal? stop : continue]

---

Virtual Fences

Directory: oculus-api/oculus/virtual_fences/

Pattern-detected markdown structures treated as stateful fences.

Virtual Fence	File	Detects
TodoListVirtualFence	todo_list.py	- [ ] checkbox lists
InventoryVirtualFence	inventory.py	Inventory with quantities
MetadataVirtualFence	metadata_virtual_fence.py	Composite metadata
ScheduleTemplateVirtualFence	schedule_template.py	Recurring tasks
CalloutVirtualFence	callout.py	GitHub-style callouts
BadgesVirtualFence	badges.py	Inline status badges
SlotVirtualFence	slot_provider.py:454	Navigation slots
FenceParamsVirtualFence	fence_params.py	Parameter documentation
ProvenanceVirtualFence	provenance_virtual_fence.py	Hash verification

---

Fence URL Parsing

File: oculus-api/oculus/fence_url_parser.py

Parses fence info strings like aws:ec2:describe_instances:table[execute=true]

Class	Purpose
FenceInfo	Dataclass holding parsed components
FenceURLParser	Parser with _determine_min_level()
parse_fence_info()	Main entry function

---

Key Data Structures

FenceExecutionContext (fence_executor.py:67)

slug: str           # Current node
mode: str           # 'backend' | 'frontend'
registry            # Node registry
credentials: Dict   # API keys, tokens
graph               # Graph reference
outputs: Dict       # Named fence outputs (pipeline pattern)
fence_info: FenceInfo  # Parsed fence URL

Middleware.process() signature

def process(self, data: Any, context: Dict[str, Any]) -> Any

Context contains: fence_type, data_type, slug, warnings, debug

Provider result contract

{
    'data': <any>,           # The actual result
    'metadata': {...},       # Type, provider info
    'error': None | str      # Error message if failed
}

---

Rendering Levels (Beanstalk)

These levels are conceptual - actual implementation spread across files:

Level	What happens	Where
RAW	Parse markdown → tokens	Parser (markdown-it)
SUBSTITUTED	Resolve ${...}	VariableInterpolatorMiddleware:1767
INTERPOLATED	Expand {{...}}	IncludeExpanderMiddleware:1828
RENDERED	Execute fences	FenceExecutorMiddleware:1892

---

Finding Your Way

"How does X execute?" → Check providers/ for the provider class, look at can_execute() and execute()

"How is data transformed?" → Check middleware.py, find the middleware class, look at process()

"Where does the API call go?" → Start at api.py, find the endpoint, trace into fence_executor

"How do virtual fences work?" → Check virtual_fences/, look at detect() and render() methods

North

slots:
- context:
  - Linking architecture doc to main oculus node
  slug: oculus

East

slots:
- context:
  - Linking to middleware library for deeper dive
  slug: middleware-library