mirrors/archon
1
0
Fork 0
mirror of https://github.com/coleam00/Archon.git synced 2025-12-24 02:39:17 -05:00
Code Issues Packages Projects Releases Wiki Activity

refactor: reorganize features/shared directory for better maintainability (#730)

Browse Source 
* refactor: reorganize features/shared directory structure

- Created organized subdirectories for better code organization:
  - api/ - API clients and HTTP utilities (renamed apiWithEtag.ts to apiClient.ts)
  - config/ - Configuration files (queryClient, queryPatterns)
  - types/ - Shared type definitions (errors)
  - utils/ - Pure utility functions (optimistic, clipboard)
  - hooks/ - Shared React hooks (already existed)

- Updated all import paths across the codebase (~40+ files)
- Updated all AI documentation in PRPs/ai_docs/ to reflect new structure
- All tests passing, build successful, no functional changes

This improves maintainability and follows vertical slice architecture patterns.

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: address PR review comments and code improvements

- Update imports to use @/features alias path for optimistic utils
- Fix optimistic upload item replacement by matching on source_id instead of id
- Clean up test suite naming and remove meta-terms from comments
- Only set Content-Type header on requests with body
- Add explicit TypeScript typing to useProjectFeatures hook
- Complete Phase 4 improvements with proper query typing

* fix: address additional PR review feedback

- Clear feature queries when deleting project to prevent cache memory leaks
- Update KnowledgeCard comments to follow documentation guidelines
- Add explanatory comment for accessibility pattern in KnowledgeCard

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Wirasm
2025-09-22 14:59:33 +03:00
committed by GitHub
parent d3a5c3311a
commit 63a92cf7d7
48 changed files with 230 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
PRPs/ai_docs/API_NAMING_CONVENTIONS.md
View File

@@ -198,7 +198,7 @@ Database values used directly - no mapping layers:
- Operation statuses: `"pending"`, `"processing"`, `"completed"`, `"failed"`
### Time Constants
**Location**: `archon-ui-main/src/features/shared/queryPatterns.ts`
**Location**: `archon-ui-main/src/features/shared/config/queryPatterns.ts`
- `STALE_TIMES.instant` - 0ms
- `STALE_TIMES.realtime` - 3 seconds
- `STALE_TIMES.frequent` - 5 seconds

6
PRPs/ai_docs/ARCHITECTURE.md
View File

@@ -88,8 +88,8 @@ Pattern: `{METHOD} /api/{resource}/{id?}/{sub-resource?}`
### Data Fetching
**Core**: TanStack Query v5
**Configuration**: `archon-ui-main/src/features/shared/queryClient.ts`
**Patterns**: `archon-ui-main/src/features/shared/queryPatterns.ts`
**Configuration**: `archon-ui-main/src/features/shared/config/queryClient.ts`
**Patterns**: `archon-ui-main/src/features/shared/config/queryPatterns.ts`
### State Management
- **Server State**: TanStack Query
@@ -139,7 +139,7 @@ TanStack Query is the single source of truth. No separate state management neede
No translation layers. Database values (e.g., `"todo"`, `"doing"`) used directly in UI.
### Browser-Native Caching
ETags handled by browser, not JavaScript. See `archon-ui-main/src/features/shared/apiWithEtag.ts`.
ETags handled by browser, not JavaScript. See `archon-ui-main/src/features/shared/api/apiClient.ts`.
## Deployment

10
PRPs/ai_docs/DATA_FETCHING_ARCHITECTURE.md
View File

@@ -8,7 +8,7 @@ Archon uses **TanStack Query v5** for all data fetching, caching, and synchroniz
### 1. Query Client Configuration
**Location**: `archon-ui-main/src/features/shared/queryClient.ts`
**Location**: `archon-ui-main/src/features/shared/config/queryClient.ts`
Centralized QueryClient with:
@@ -30,7 +30,7 @@ Visibility-aware polling that:
### 3. Query Patterns
**Location**: `archon-ui-main/src/features/shared/queryPatterns.ts`
**Location**: `archon-ui-main/src/features/shared/config/queryPatterns.ts`
Shared constants:
@@ -64,7 +64,7 @@ Standard pattern across all features:
### ETag Support
**Location**: `archon-ui-main/src/features/shared/apiWithEtag.ts`
**Location**: `archon-ui-main/src/features/shared/api/apiClient.ts`
ETag implementation:
@@ -83,7 +83,7 @@ Backend endpoints follow RESTful patterns:
## Optimistic Updates
**Utilities**: `archon-ui-main/src/features/shared/optimistic.ts`
**Utilities**: `archon-ui-main/src/features/shared/utils/optimistic.ts`
All mutations use nanoid-based optimistic updates:
@@ -105,7 +105,7 @@ Polling intervals are defined in each feature's query hooks. See actual implemen
- **Progress**: `archon-ui-main/src/features/progress/hooks/useProgressQueries.ts`
- **MCP**: `archon-ui-main/src/features/mcp/hooks/useMcpQueries.ts`
Standard intervals from `archon-ui-main/src/features/shared/queryPatterns.ts`:
Standard intervals from `archon-ui-main/src/features/shared/config/queryPatterns.ts`:
- `STALE_TIMES.instant`: 0ms (always fresh)
- `STALE_TIMES.frequent`: 5 seconds (frequently changing data)
- `STALE_TIMES.normal`: 30 seconds (standard cache)

10
PRPs/ai_docs/ETAG_IMPLEMENTATION.md
View File

@@ -17,7 +17,7 @@ The backend generates ETags for API responses:
- Returns `304 Not Modified` when ETags match
### Frontend Handling
**Location**: `archon-ui-main/src/features/shared/apiWithEtag.ts`
**Location**: `archon-ui-main/src/features/shared/api/apiClient.ts`
The frontend relies on browser-native HTTP caching:
- Browser automatically sends `If-None-Match` headers with cached ETags
@@ -28,7 +28,7 @@ The frontend relies on browser-native HTTP caching:
#### Browser vs Non-Browser Behavior
- **Standard Browsers**: Per the Fetch spec, a 304 response freshens the HTTP cache and returns the cached body to JavaScript
- **Non-Browser Runtimes** (React Native, custom fetch): May surface 304 with empty body to JavaScript
- **Client Fallback**: The `apiWithEtag.ts` implementation handles both scenarios, ensuring consistent behavior across environments
- **Client Fallback**: The `apiClient.ts` implementation handles both scenarios, ensuring consistent behavior across environments
## Implementation Details
@@ -81,8 +81,8 @@ Unlike previous implementations, the current approach:
### Configuration
Cache behavior is controlled through TanStack Query's `staleTime`:
- See `archon-ui-main/src/features/shared/queryPatterns.ts` for standard times
- See `archon-ui-main/src/features/shared/queryClient.ts` for global configuration
- See `archon-ui-main/src/features/shared/config/queryPatterns.ts` for standard times
- See `archon-ui-main/src/features/shared/config/queryClient.ts` for global configuration
## Performance Benefits
@@ -100,7 +100,7 @@ Cache behavior is controlled through TanStack Query's `staleTime`:
### Core Implementation
- **Backend Utilities**: `python/src/server/utils/etag_utils.py`
- **Frontend Client**: `archon-ui-main/src/features/shared/apiWithEtag.ts`
- **Frontend Client**: `archon-ui-main/src/features/shared/api/apiClient.ts`
- **Tests**: `python/tests/server/utils/test_etag_utils.py`
### Usage Examples

8
PRPs/ai_docs/QUERY_PATTERNS.md
View File

@@ -5,7 +5,7 @@ This guide documents the standardized patterns for using TanStack Query v5 in th
## Core Principles
1. **Feature Ownership**: Each feature owns its query keys in `{feature}/hooks/use{Feature}Queries.ts`
2. **Consistent Patterns**: Always use shared patterns from `shared/queryPatterns.ts`
2. **Consistent Patterns**: Always use shared patterns from `shared/config/queryPatterns.ts`
3. **No Hardcoded Values**: Never hardcode stale times or disabled keys
4. **Mirror Backend API**: Query keys should exactly match backend API structure
@@ -49,7 +49,7 @@ export const taskKeys = {
### Import Required Patterns
```typescript
import { DISABLED_QUERY_KEY, STALE_TIMES } from "@/features/shared/queryPatterns";
import { DISABLED_QUERY_KEY, STALE_TIMES } from "@/features/shared/config/queryPatterns";
```
### Disabled Queries
@@ -106,7 +106,7 @@ export function useFeatureDetail(id: string | undefined) {
## Mutations with Optimistic Updates
```typescript
import { createOptimisticEntity, replaceOptimisticEntity } from "@/features/shared/optimistic";
import { createOptimisticEntity, replaceOptimisticEntity } from "@/features/shared/utils/optimistic";
export function useCreateFeature() {
const queryClient = useQueryClient();
@@ -161,7 +161,7 @@ vi.mock("../../services", () => ({
}));
// Mock shared patterns with ALL values
vi.mock("../../../shared/queryPatterns", () => ({
vi.mock("../../../shared/config/queryPatterns", () => ({
DISABLED_QUERY_KEY: ["disabled"] as const,
STALE_TIMES: {
instant: 0,

6
PRPs/ai_docs/optimistic_updates.md
View File

@@ -3,7 +3,7 @@
## Core Architecture
### Shared Utilities Module
**Location**: `src/features/shared/optimistic.ts`
**Location**: `src/features/shared/utils/optimistic.ts`
Provides type-safe utilities for managing optimistic state across all features:
- `createOptimisticId()` - Generates stable UUIDs using nanoid
@@ -73,13 +73,13 @@ Reusable component showing:
- Uses `createOptimisticId()` directly for progress tracking
### Toasts
- **Location**: `src/features/ui/hooks/useToast.ts:43`
- **Location**: `src/features/shared/hooks/useToast.ts:43`
- Uses `createOptimisticId()` for unique toast IDs
## Testing
### Unit Tests
**Location**: `src/features/shared/optimistic.test.ts`
**Location**: `src/features/shared/utils/tests/optimistic.test.ts`
Covers all utility functions with 8 test cases:
- ID uniqueness and format validation