why-do-we-use-oculus
Document why-do-we-use-oculus
Summary
This is an actual session of Claude Code that started from fresh context.
My team asked "why should we use Oculus" in our team chat this morning. This was my response
(for context, yesterday was the first day we started using oculus to document the existing system). We had a ticket yesterday to migrate the PQIS-RADUI from its internal presence in preprod to be a standard public-facing (but restricted) application)
The scenario:
Simulate an incoming ticket from a team requesting a new pipeline be setup. It was presented with the typical minimal information you would get from a team - "we need a new Angular application deployed to ECS behind nginx".
The outcome:
- the system identified the correct pattern to match on after navigating our knowledgge graph with minimal input
- the node that provided the required information was also agentically generated as an artifact of regular work - in this case, grooming a ticket
- the system provided scaffolded configuration for the new service with clear placeholders for required configurations
- the system suggested a series of valid questions, all generated to request the missing context that would be required to complete the requested work
This is an automated response to a real world scenario that was generated with a simple conversational request using Oculus as a spatially navigated knowledge base, a pointer to a central node that provides an easy to remember entrypoint to the graph, and some AI generated artifacts that represent the existing deployment patterns (that only exist as a side effect of using the platform to solve real world problems).
The Claude Code Session
> We're going to do a simulation, so we're going to pretend we got a Jira ticket from the
PQIS Dev Team to my to create a new service. The new service is going to be another
Angular application. It's a standalone application, it's going to be served behind Nginx,
and it needs to be deployed out to ECS.
What I would like you to do is go to the PQIS node, and then navigate south. Drill into
their deployments south of the PQIS node in Oculus. You will find a listing of their
current services that are being deployed. See if you can find one that's close, and then
come up with a recommendation for how we should deploy it. Include any examples of code
that you can work out. Include any questions that might need to be asked about
configurations. Assume that all we have is just a basic request, a pointer to a
repository, and we've been told that it's an Angular single-page application.
⏺ I'll help you explore the PQIS deployment structure in Oculus to find a similar Angular
application deployment pattern. Let me navigate to the PQIS node and explore what's
south of it.
⏺ wanderland - oculus_goto (MCP)(slug: "pqis")
⎿ {
"slug": "pqis",
"node": {
… +35 lines (ctrl+o to expand)
⏺ Great! I can see the PQIS node has two south directions: pqis-load-balancers and
pqis-services. Let me navigate to the services node to see what's deployed.
⏺ wanderland - oculus_goto (MCP)(slug: "pqis-services")
⎿ {
"slug": "pqis-services",
"node": {
… +49 lines (ctrl+o to expand)
⏺ Excellent! I can see the PQIS services structure. There are two services visible to the
south: pqis-radui and pqis-pam. The pqis-radui (RAD UI) sounds like it could be a UI
application that might be Angular-based. Let me explore that one first.
⏺ wanderland - oculus_goto (MCP)(slug: "pqis-radui")
⎿ {
"slug": "pqis-radui",
"node": {
… +79 lines (ctrl+o to expand)
⏺ Perfect! I found exactly what we need. RadUI is an Angular single-page application
served behind nginx and deployed to AWS ECS - this is a perfect match for your scenario.
Let me grab the actual deployment configuration files to show you the pattern:
⏺ Read(radui/jenkins/deploy.yml)
⎿ Read 379 lines
⏺ Read(radui/jenkins/preprod.yml)
⎿ Read 176 lines
⏺ Read(radui/jenkins/prod.yml)
⎿ Read 184 lines
⏺ Now let me look at the Dockerfile and nginx configuration to understand the complete
picture:
⏺ Search(pattern: "**/Dockerfile", path: "radui")
⎿ Found 1 file (ctrl+o to expand)
⏺ Search(pattern: "**/*.conf", path: "radui")
⎿ Found 0 files
⏺ Read(radui/Dockerfile)
⎿ Read 16 lines
⏺ Search(pattern: "**/*.erb", path: "radui")
⎿ Found 4 files (ctrl+o to expand)
⏺ Read(radui/config/preprod.conf.erb)
⎿ Read 112 lines
⏺ Let me check the CloudFormation template being used:
⏺ Bash(ls -la /Users/graemefawcett/working/pqis-app-deployment/cloudformation/docker/ | grep
-i "https_alb_with_dns_env_int")
⎿ -rw-r--r-- 1 graemefawcett staff 13148 Jan 29 2025 http_https_alb_with_dns_env_i
nt.json
-rw-r--r-- 1 graemefawcett staff 6416 Jan 29 2025 https_alb_with_dns_env_int_th
… +9 lines (ctrl+o to expand)
⏺ Perfect! I have everything I need. Let me create a comprehensive recommendation for you
based on the RadUI deployment pattern.
Deployment Recommendation for New Angular Application
Based on my exploration of the PQIS services, RadUI is the perfect template for your new
Angular SPA deployment. It's an Angular application served behind nginx and deployed to
AWS ECS.
Key Architecture Pattern
Angular Build → Docker Image (nginx + static files) → ECR → ECS (Fargate/EC2) → ALB →
Route53
Required Repository Structure
Your new service will need these files in pqis-app-deployment/{service-name}/:
1. jenkins/deploy.yml (Main deployment configuration)
Key sections:
pipeline:
metadata:
group: pqis
name: pqis-pqp-{service}-webapp-{env}-{subenv}-pipeline
tags:
system: pqp.{service}.webapp
environment: devl/preprod/prod
sub_environment: nightly1/main/etc
urls:
base: {service}-{version}.{env}.int.proquest.com
common: {service}.{env}.int.proquest.com
stages:
build: # Build Angular app → tarball → S3
label: node-ec2
tools:
nodejs: 22.3.0
scm:
url: https://github.com/clarivate-prod/{repo-name}.git
branch: main
builder:
type: script
args:
script: |
npm install
npm run build
tar -czvf {service}-v${RELEASE}.tar.gz dist
image: # Download artifact, build multi-arch Docker image
label: docker-ec2
downloader:
type: s3
builder:
type: ecrDockerMultiArch
args:
platforms:
- linux/amd64
- linux/arm64
deploy: # Deploy to ECS via CloudFormation
deployer:
type: ecsService
validate: # Wait for healthy deployment
validator:
type: ecsService
args:
targetGroupResources:
- DefaultALBTargetGroup
publish: # Activate and configure auto-scaling
publisher:
type: ecsService
2. Dockerfile
FROM public.ecr.aws/nginx/nginx
LABEL Name=pqis/{service}
LABEL Version=1.0.0
RUN mkdir /app
COPY {service}.tar.gz /app
RUN cd /app;\
tar xzf {service}.tar.gz
COPY config/*.conf /etc/nginx/
CMD nginx -c /etc/nginx/devl.conf
3. nginx Configuration Files
Create config/{env}.conf.erb for each environment (devl, preprod, prod):
daemon off;
user nginx;
worker_processes 1;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;
events {
worker_connections 1024;
}
http {
include /etc/nginx/mime.types;
default_type application/octet-stream;
access_log /var/log/nginx/access.log main;
gzip on;
gzip_types text/plain text/xml text/css
text/javascript
application/x-javascript
application/atom+xml;
server {
listen 80;
server_name {service}.{env}.int.proquest.com;
root /app/dist;
index index.html;
# SPA routing - all routes serve index.html
try_files $uri $uri/ /index.html;
# Force HTTPS when behind ALB
if ($http_x_forwarded_proto != "https") {
return 301 https://$host$request_uri;
}
}
}
4. ECS Task Configuration (in deploy.yml)
components:
default:
cloudformation:
template: cloudformation/docker/https_alb_with_dns_env_int_three_az.yml
parameters:
ALBScheme: internal # or 'external' for public access
AvailabilityZoneA: us-east-1a
AvailabilityZoneB: us-east-1c
AvailabilityZoneC: us-east-1f
HealthCheckMatcher: 200-399
HealthCheckPath: /
IdleTimeout: 300
ecs:
metadata:
cluster: pqis-{env}-{arch} # e.g., pqis-preprod-v2-arm64
service_name: {service}-{env}-{version}
task_name: {service}-{env}
task:
container_definitions:
- command: ["nginx", "-c", "/etc/nginx/{env}.conf"]
cpu: 256
memory: 1024
essential: true
image: !Mapped pipeline.artifacts.image.tag
port_mappings:
- container_port: 80
protocol: tcp
service:
desired_count: 2
deployment_configuration:
maximum_percent: 200
minimum_healthy_percent: 50
scaling_parameters:
cooldown: 300
scaling_enabled:
cpu: true
memory: false
thresholds:
containers:
min: 2
max: 20
cpu:
min: 10
max: 70
Critical Questions to Ask
1. Service Identity
- What is the service name? (e.g., "myapp")
- What is the complete system tag? (Format: pqp.{service}.webapp)
- Repository URL?
- What is the build output directory? (e.g., dist, build, www)
2. Environment Strategy
- Which environments needed? (devl nightly1-4, preprod, prod)
- Which ECS clusters to target?
- Development: pqis-nightly{N}-arm64
- Preprod: pqis-preprod-v2-arm64
- Prod: pqis-prod-subscriber-arm64 or pqis-prod-openlayer-arm64
3. DNS & Networking
- Internal or external access? (affects ALBScheme)
- DNS pattern: {service}.{env}.int.proquest.com?
- Custom domain requirements?
- Cloudflare protection needed?
4. Build Configuration
- Node.js version required? (RadUI uses 22.3.0)
- Custom build commands beyond npm install && npm run build?
- Environment-specific build configurations?
- Any build-time secrets/config needed?
5. Runtime Configuration
- Backend API endpoints to proxy? (Like RadUI proxies /rad/*)
- Authentication requirements?
- Special nginx configurations? (IP whitelisting, rate limiting, etc.)
- Custom HTTP headers needed?
6. Resource Allocation
- CPU/Memory requirements (default: 256 CPU units, 1024 MB)
- Auto-scaling parameters (default: 2-20 containers, 10-70% CPU)
- Health check path (default: /)
7. Release Management
- Which automated release trains? (e.g., pqp-preprod-release)
- Release check-in phases?
- Promotion strategy (preprod → prod)?
Jenkins Pipeline Creation
You'll need to create these Jenkins jobs:
pqis-pqp-{service}-webapp-devl-nightly1-pipeline
pqis-pqp-{service}-webapp-devl-nightly2-pipeline
pqis-pqp-{service}-webapp-preprod-main-pipeline
pqis-pqp-{service}-webapp-prod-main-pipeline
Example: Creating "myapp" Service
If the new service is called "myapp", you would:
1. Create directory structure:
pqis-app-deployment/myapp/
├── Dockerfile
├── jenkins/
│ ├── deploy.yml
│ ├── preprod.yml
│ └── prod.yml
└── config/
├── devl.conf.erb
├── preprod.conf.erb
└── prod.conf.erb
2. Use system tag: pqp.myapp.webapp
3. S3 artifact path: s3://pqis-apps/myapp/artifacts/
4. ECR image: 365859773477.dkr.ecr.us-east-1.amazonaws.com/pqis/myapp
Would you like me to generate the actual configuration files for your specific new
service? I'll need the answers to the critical questions above to customize them
properly.North
slots: []South
slots: []East
slots: []West
slots: []tags
tags: []