Skip to content

Commit 03a1ba3

Browse files
fearnworksfearnworks
authored
Batch Job Table & Architecture doc update (#31)
* Update task plan for P1/P2 Signed-off-by: jphillips <josh.phillips@fearnworks.com> * Batch Queue DB & API Signed-off-by: jphillips <josh.phillips@fearnworks.com> * Add architecture docs & message broker design Signed-off-by: jphillips <josh.phillips@fearnworks.com> * Add message broker Signed-off-by: jphillips <josh.phillips@fearnworks.com> * arch update for discussion Signed-off-by: jphillips <josh.phillips@fearnworks.com> * update data service doc Signed-off-by: jphillips <josh.phillips@fearnworks.com> * remove message broker doc Signed-off-by: jphillips <josh.phillips@fearnworks.com> * update arch docs, remove broker Signed-off-by: jphillips <josh.phillips@fearnworks.com> * Cleanup Signed-off-by: jphillips <josh.phillips@fearnworks.com> --------- Signed-off-by: jphillips <josh.phillips@fearnworks.com>
1 parent 9106f4b commit 03a1ba3

23 files changed

Lines changed: 2836 additions & 310 deletions

‎.cursor/rules/modern-react-components.mdc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description:
33
globs:
4-
alwaysApply: true
4+
alwaysApply: false
55
---
66

77
# Creating Modern React Components in 2025

‎.cursor/rules/task.mdc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,4 +4,4 @@ globs:
44
alwaysApply: true
55
---
66
# Task
7-
Insert the task for the agent.
7+
Add your task for the agent here.

‎doc/concepts/perspectives.rst‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
===========================
2-
Perspectives in GraphCap
2+
Perspectives in graphcap
33
===========================
44

5-
Think of a perspective as a unique way of looking at and describing an image. Just like how a photographer, an art critic, and a child might describe the same photograph differently, GraphCap uses different perspectives to capture various aspects of what makes an image meaningful.
5+
Think of a perspective as a unique way of looking at and describing an image. Just like how a photographer, an art critic, and a child might describe the same photograph differently, graphcap uses different perspectives to capture various aspects of what makes an image meaningful.
66

77
What's in a Perspective?
88
=======================
@@ -28,7 +28,7 @@ Each perspective has its own:
2828
The Perspective Ecosystem
2929
========================
3030

31-
Perspectives in GraphCap are organized into modules that group related perspectives together. This organization makes it easier to:
31+
Perspectives in graphcap are organized into modules that group related perspectives together. This organization makes it easier to:
3232

3333
- Find perspectives relevant to your interests
3434
- Enable or disable entire families of perspectives
@@ -45,7 +45,7 @@ Examples of modules include:
4545
Built-in Perspectives
4646
===================
4747

48-
GraphCap comes with a diverse set of built-in perspectives, each designed for specific use cases:
48+
graphcap comes with a diverse set of built-in perspectives, each designed for specific use cases:
4949

5050
Graph Caption
5151
------------
@@ -89,7 +89,7 @@ Working with Perspectives
8989

9090
Discovering and Selecting
9191
------------------------
92-
GraphCap offers an intuitive way to browse and select perspectives:
92+
graphcap offers an intuitive way to browse and select perspectives:
9393

9494
- Browse by module to find related perspectives
9595
- Filter by tags to find perspectives for specific needs
@@ -107,13 +107,13 @@ Perspectives work best when they complement each other. You might use:
107107
Local Development and Customization
108108
=================================
109109

110-
GraphCap allows you to create and test new perspectives locally before sharing them more broadly:
110+
graphcap allows you to create and test new perspectives locally before sharing them more broadly:
111111

112112
Perspective Workspace
113113
-------------------
114114
Your perspective library can include both:
115115

116-
- Standard perspectives from the GraphCap library
116+
- Standard perspectives from the graphcap library
117117
- Local perspectives you're developing or customizing
118118

119119
This separation lets you experiment with new ideas while keeping the main system stable.
@@ -193,7 +193,7 @@ As your needs evolve, perspectives can too:
193193
Real-World Usage
194194
==============
195195

196-
GraphCap perspectives are designed to be useful in real-world applications:
196+
graphcap perspectives are designed to be useful in real-world applications:
197197

198198
- **Content Creation**: Generate rich, varied descriptions for creative projects
199199
- **Accessibility**: Provide detailed image descriptions for visually impaired users

‎doc/dev/architecture.rst‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
=================================
2+
graphcap Architecture Overview
3+
=================================
4+
5+
Audience and Architectural Principles
6+
=====================================
7+
8+
This document targets system architects and software engineers maintaining or extending the graphcap system.
9+
10+
graphcap is designed explicitly for small to medium-sized on-premises or single-user deployments, adopting a local-first architecture. The system prioritizes:
11+
12+
- **Offline-first Operation**: Capable of functioning with intermittent or no internet connectivity.
13+
- **Local Data Sovereignty**: Data persists locally and synchronizes opportunistically.
14+
- **Modular and Extensible Components**: Clear service boundaries and stateless design patterns for maintainability.
15+
16+
17+
System Components
18+
=================
19+
20+
graphcap consists of specialized services working together to provide image captioning capabilities:
21+
22+
- **React Client**: Web-based user interface and system orchestrator.
23+
- **Data Service**: Manages database operations and data persistence.
24+
- **Inference Bridge**: Performs AI-based image captioning.
25+
- **Media Server**: Manages image storage, retrieval, and processing.
26+
27+
.. figure::
28+
29+
.. code-block:: text
30+
31+
┌─────────────────────────────────────┐
32+
│ React Client │
33+
│ (Orchestrator) │
34+
└───────┬─────────┬─────────┬─────────┘
35+
│ │ │
36+
│ │ │
37+
▼ ▼ ▼
38+
┌───────────┐ ┌───────────┐ ┌─────────────┐
39+
│ Data │ │ Inference │ │ Media Server│
40+
│ Service │ │ Bridge │ │ │
41+
└─────┬─────┘ └─────┬─────┘ └──────┬──────┘
42+
│ │ │
43+
▼ │ │
44+
┌──────────┐ │ │
45+
│PostgreSQL│ │ │
46+
└──────────┘ │ │
47+
│ │
48+
▼ ▼
49+
┌─────────────────────────┐
50+
│ Workspace Volume │
51+
│ (Shared Storage) │
52+
└─────────────────────────┘
53+
54+
55+
Communication Flows
56+
===================
57+
58+
REST API Communication
59+
----------------------
60+
61+
The React Client orchestrates all services through direct REST API calls:
62+
63+
- **Client ↔ Data Service**: Database operations, caption storage, retrieval.
64+
- **Client ↔ Inference Bridge**: Caption generation requests and responses.
65+
- **Client ↔ Media Server**: Image upload, retrieval, processing, file system operations.
66+
67+
Independent Service Operation
68+
----------------------------
69+
70+
Each service operates independently without direct communication with other services:
71+
72+
- **Data Service**: Persists caption data, handles database operations.
73+
- **Inference Bridge**: Processes image captioning requests when invoked.
74+
- **Media Server**: Manages file operations and image processing.
75+
76+
All services directly access the shared workspace volume for file operations.
77+
78+
WebSocket Communication
79+
-----------------------
80+
81+
Real-time updates may be implemented through direct WebSocket connections:
82+
83+
- **Data Service → Client**: Database updates and events.
84+
- **Inference Bridge → Client**: Caption processing status.
85+
86+
87+
Component Deep Dives
88+
====================
89+
90+
Data Service
91+
------------
92+
93+
Manages data persistence and database operations:
94+
95+
- Single source of truth via PostgreSQL.
96+
- Stores caption data, metadata, and relationships.
97+
- Provides REST APIs for data retrieval and modification.
98+
- Only service with direct PostgreSQL access.
99+
100+
Inference Bridge
101+
----------------
102+
103+
Stateless AI caption processing:
104+
105+
- Receives caption requests directly from the client.
106+
- Communicates with AI providers (Gemini, Ollama, OpenAI).
107+
- Returns results directly to the client.
108+
- Remains completely stateless.
109+
- Reads images from the shared workspace volume.
110+
111+
Media Server
112+
------------
113+
114+
Responsible for media asset management:
115+
116+
- Provides file upload, retrieval, and processing APIs.
117+
- Manages workspace directory structure.
118+
- Generates thumbnails, extracts metadata.
119+
- Handles all file system operations on the workspace.
120+
121+
React Client
122+
------------
123+
124+
Interactive front-end interface and system orchestrator:
125+
126+
- Orchestrates workflow between services.
127+
- Directly communicates with all services.
128+
- Manages UI state and user experience.
129+
- Coordinates business logic and process flow.
130+
- Utilizes TanStack Query for efficient state management.
131+
132+
133+

0 commit comments

Comments
 (0)