1b272ed2af
* docs: Update AI documentation for accurate codebase reflection - Replace obsolete POLLING_ARCHITECTURE.md with DATA_FETCHING_ARCHITECTURE.md - Rewrite API_NAMING_CONVENTIONS.md with file references instead of code examples - Condense ARCHITECTURE.md from 482 to 195 lines for clarity - Update ETAG_IMPLEMENTATION.md to reflect actual implementation - Update QUERY_PATTERNS.md to reflect completed Phase 5 (nanoid optimistic updates) - Add PRPs/stories/ to .gitignore All documentation now references actual files in codebase rather than embedding potentially stale code examples. * docs: Update CLAUDE.md and AGENTS.md with current patterns - Update CLAUDE.md to reference documentation files instead of embedding code - Replace Service Layer and Error Handling code examples with file references - Add proper distinction between DATA_FETCHING_ARCHITECTURE and QUERY_PATTERNS docs - Include ETag implementation reference - Update environment variables section with .env.example reference * docs: apply PR review improvements to AI documentation - Fix punctuation, hyphenation, and grammar issues across all docs - Add language tags to directory tree code blocks for proper markdown linting - Clarify TanStack Query integration (not replacing polling, but integrating it) - Add Cache-Control header documentation and browser vs non-browser fetch behavior - Reference actual implementation files for polling intervals instead of hardcoding values - Improve type-safety phrasing and remove line numbers from file references - Clarify Phase 1 removed manual frontend ETag cache (backend ETags remain)
249 lines
7.8 KiB
Markdown
249 lines
7.8 KiB
Markdown
# API Naming Conventions
|
|
|
|
## Overview
|
|
|
|
This document describes the actual naming conventions used throughout Archon's codebase based on current implementation patterns. All examples reference real files where these patterns are implemented.
|
|
|
|
## Backend API Endpoints
|
|
|
|
### RESTful Route Patterns
|
|
**Reference**: `python/src/server/api_routes/projects_api.py`
|
|
|
|
Standard REST patterns used:
|
|
- `GET /api/{resource}` - List all resources
|
|
- `POST /api/{resource}` - Create new resource
|
|
- `GET /api/{resource}/{id}` - Get single resource
|
|
- `PUT /api/{resource}/{id}` - Update resource
|
|
- `DELETE /api/{resource}/{id}` - Delete resource
|
|
|
|
Nested resource patterns:
|
|
- `GET /api/projects/{project_id}/tasks` - Tasks scoped to project
|
|
- `GET /api/projects/{project_id}/docs` - Documents scoped to project
|
|
- `POST /api/projects/{project_id}/versions` - Create version for project
|
|
|
|
### Actual Endpoint Examples
|
|
From `python/src/server/api_routes/`:
|
|
|
|
**Projects** (`projects_api.py`):
|
|
- `/api/projects` - Project CRUD
|
|
- `/api/projects/{project_id}/features` - Get project features
|
|
- `/api/projects/{project_id}/tasks` - Project-scoped tasks
|
|
- `/api/projects/{project_id}/docs` - Project documents
|
|
- `/api/projects/{project_id}/versions` - Version history
|
|
|
|
**Knowledge** (`knowledge_api.py`):
|
|
- `/api/knowledge/sources` - Knowledge sources
|
|
- `/api/knowledge/crawl` - Start web crawl
|
|
- `/api/knowledge/upload` - Upload document
|
|
- `/api/knowledge/search` - RAG search
|
|
- `/api/knowledge/code-search` - Code-specific search
|
|
|
|
**Progress** (`progress_api.py`):
|
|
- `/api/progress/active` - Active operations
|
|
- `/api/progress/{operation_id}` - Specific operation status
|
|
|
|
**MCP** (`mcp_api.py`):
|
|
- `/api/mcp/status` - MCP server status
|
|
- `/api/mcp/execute` - Execute MCP tool
|
|
|
|
## Frontend Service Methods
|
|
|
|
### Service Object Pattern
|
|
**Reference**: `archon-ui-main/src/features/projects/services/projectService.ts`
|
|
|
|
Services are exported as objects with async methods:
|
|
```typescript
|
|
export const serviceNameService = {
|
|
async methodName(): Promise<ReturnType> { ... }
|
|
}
|
|
```
|
|
|
|
### Standard Service Method Names
|
|
Actual patterns from service files:
|
|
|
|
**List Operations**:
|
|
- `listProjects()` - Get all projects
|
|
- `getTasksByProject(projectId)` - Get filtered list
|
|
- `getTasksByStatus(status)` - Get by specific criteria
|
|
|
|
**Single Item Operations**:
|
|
- `getProject(projectId)` - Get single item
|
|
- `getTask(taskId)` - Direct ID access
|
|
|
|
**Create Operations**:
|
|
- `createProject(data)` - Returns created entity
|
|
- `createTask(data)` - Includes server-generated fields
|
|
|
|
**Update Operations**:
|
|
- `updateProject(id, updates)` - Partial updates
|
|
- `updateTaskStatus(id, status)` - Specific field update
|
|
- `updateTaskOrder(id, order, status?)` - Complex updates
|
|
|
|
**Delete Operations**:
|
|
- `deleteProject(id)` - Returns void
|
|
- `deleteTask(id)` - Soft delete pattern
|
|
|
|
### Service File Locations
|
|
- **Projects**: `archon-ui-main/src/features/projects/services/projectService.ts`
|
|
- **Tasks**: `archon-ui-main/src/features/projects/tasks/services/taskService.ts`
|
|
- **Knowledge**: `archon-ui-main/src/features/knowledge/services/knowledgeService.ts`
|
|
- **Progress**: `archon-ui-main/src/features/progress/services/progressService.ts`
|
|
|
|
## React Hook Naming
|
|
|
|
### Query Hooks
|
|
**Reference**: `archon-ui-main/src/features/projects/tasks/hooks/useTaskQueries.ts`
|
|
|
|
Standard patterns:
|
|
- `use[Resource]()` - List query (e.g., `useProjects`)
|
|
- `use[Resource]Detail(id)` - Single item query
|
|
- `use[Parent][Resource](parentId)` - Scoped query (e.g., `useProjectTasks`)
|
|
|
|
### Mutation Hooks
|
|
- `useCreate[Resource]()` - Creation mutation
|
|
- `useUpdate[Resource]()` - Update mutation
|
|
- `useDelete[Resource]()` - Deletion mutation
|
|
|
|
### Utility Hooks
|
|
**Reference**: `archon-ui-main/src/features/ui/hooks/`
|
|
- `useSmartPolling()` - Visibility-aware polling
|
|
- `useToast()` - Toast notifications
|
|
- `useDebounce()` - Debounced values
|
|
|
|
## Type Naming Conventions
|
|
|
|
### Type Definition Patterns
|
|
**Reference**: `archon-ui-main/src/features/projects/types/`
|
|
|
|
**Entity Types**:
|
|
- `Project` - Core entity type
|
|
- `Task` - Business object
|
|
- `Document` - Data model
|
|
|
|
**Request/Response Types**:
|
|
- `Create[Entity]Request` - Creation payload
|
|
- `Update[Entity]Request` - Update payload
|
|
- `[Entity]Response` - API response wrapper
|
|
|
|
**Database Types**:
|
|
- `DatabaseTaskStatus` - Exact database values
|
|
**Location**: `archon-ui-main/src/features/projects/tasks/types/task.ts`
|
|
Values: `"todo" | "doing" | "review" | "done"`
|
|
|
|
### Type File Organization
|
|
Following vertical slice architecture:
|
|
- Core types in `{feature}/types/`
|
|
- Sub-feature types in `{feature}/{subfeature}/types/`
|
|
- Shared types in `shared/types/`
|
|
|
|
## Query Key Factories
|
|
|
|
**Reference**: Each feature's `hooks/use{Feature}Queries.ts` file
|
|
|
|
Standard factory pattern:
|
|
- `{resource}Keys.all` - Base key for invalidation
|
|
- `{resource}Keys.lists()` - List queries
|
|
- `{resource}Keys.detail(id)` - Single item queries
|
|
- `{resource}Keys.byProject(projectId)` - Scoped queries
|
|
|
|
Examples:
|
|
- `projectKeys` - Projects domain
|
|
- `taskKeys` - Tasks (dual nature: global and project-scoped)
|
|
- `knowledgeKeys` - Knowledge base
|
|
- `progressKeys` - Progress tracking
|
|
- `documentKeys` - Document management
|
|
|
|
## Component Naming
|
|
|
|
### Page Components
|
|
**Location**: `archon-ui-main/src/pages/`
|
|
- `[Feature]Page.tsx` - Top-level pages
|
|
- `[Feature]View.tsx` - Main view components
|
|
|
|
### Feature Components
|
|
**Location**: `archon-ui-main/src/features/{feature}/components/`
|
|
- `[Entity]Card.tsx` - Card displays
|
|
- `[Entity]List.tsx` - List containers
|
|
- `[Entity]Form.tsx` - Form components
|
|
- `New[Entity]Modal.tsx` - Creation modals
|
|
- `Edit[Entity]Modal.tsx` - Edit modals
|
|
|
|
### Shared Components
|
|
**Location**: `archon-ui-main/src/features/ui/primitives/`
|
|
- Radix UI-based primitives
|
|
- Generic, reusable components
|
|
|
|
## State Variable Naming
|
|
|
|
### Loading States
|
|
**Examples from**: `archon-ui-main/src/features/projects/views/ProjectsView.tsx`
|
|
- `isLoading` - Generic loading
|
|
- `is[Action]ing` - Specific operations (e.g., `isSwitchingProject`)
|
|
- `[action]ingIds` - Sets of items being processed
|
|
|
|
### Error States
|
|
- `error` - Query errors
|
|
- `[operation]Error` - Specific operation errors
|
|
|
|
### Selection States
|
|
- `selected[Entity]` - Currently selected item
|
|
- `active[Entity]Id` - Active item ID
|
|
|
|
## Constants and Enums
|
|
|
|
### Status Values
|
|
**Location**: `archon-ui-main/src/features/projects/tasks/types/task.ts`
|
|
Database values used directly - no mapping layers:
|
|
- Task statuses: `"todo"`, `"doing"`, `"review"`, `"done"`
|
|
- Operation statuses: `"pending"`, `"processing"`, `"completed"`, `"failed"`
|
|
|
|
### Time Constants
|
|
**Location**: `archon-ui-main/src/features/shared/queryPatterns.ts`
|
|
- `STALE_TIMES.instant` - 0ms
|
|
- `STALE_TIMES.realtime` - 3 seconds
|
|
- `STALE_TIMES.frequent` - 5 seconds
|
|
- `STALE_TIMES.normal` - 30 seconds
|
|
- `STALE_TIMES.rare` - 5 minutes
|
|
- `STALE_TIMES.static` - Infinity
|
|
|
|
## File Naming Patterns
|
|
|
|
### Service Layer
|
|
- `{feature}Service.ts` - Service modules
|
|
- Use lower camelCase with "Service" suffix (e.g., `projectService.ts`)
|
|
|
|
### Hook Files
|
|
- `use{Feature}Queries.ts` - Query hooks and keys
|
|
- `use{Feature}.ts` - Feature-specific hooks
|
|
|
|
### Type Files
|
|
- `index.ts` - Barrel exports
|
|
- `{entity}.ts` - Specific entity types
|
|
|
|
### Test Files
|
|
- `{filename}.test.ts` - Unit tests
|
|
- Located in `tests/` subdirectories
|
|
|
|
## Best Practices
|
|
|
|
### Do Follow
|
|
- Use exact database values (no translation layers)
|
|
- Keep consistent patterns within features
|
|
- Use query key factories for all cache operations
|
|
- Follow vertical slice architecture
|
|
- Reference shared constants
|
|
|
|
### Don't Do
|
|
- Don't create mapping layers for database values
|
|
- Don't hardcode time values
|
|
- Don't mix query keys between features
|
|
- Don't use inconsistent naming within a feature
|
|
- Don't embed business logic in components
|
|
|
|
## Common Patterns Reference
|
|
|
|
For implementation examples, see:
|
|
- Query patterns: Any `use{Feature}Queries.ts` file
|
|
- Service patterns: Any `{feature}Service.ts` file
|
|
- Type patterns: Any `{feature}/types/` directory
|
|
- Component patterns: Any `{feature}/components/` directory |