390 lines
14 KiB
Markdown
390 lines
14 KiB
Markdown
# URL Structure Improvements Documentation
|
|
|
|
## Overview
|
|
This document outlines the comprehensive improvements made to the ATS application's URL structure to enhance consistency, maintainability, and scalability.
|
|
|
|
## Changes Made
|
|
|
|
### 1. Main Project URLs (`NorahUniversity/urls.py`)
|
|
|
|
#### API Versioning
|
|
- **Before**: `path('api/', include(router.urls))`
|
|
- **After**: `path('api/v1/', include(router.urls))`
|
|
- **Benefit**: Enables future API versioning without breaking changes
|
|
|
|
#### API Endpoint Organization
|
|
- **Before**:
|
|
- `path('api/templates/', ...)`
|
|
- `path('api/webhook/', ...)`
|
|
- **After**:
|
|
- `path('api/v1/templates/', ...)`
|
|
- `path('api/v1/webhooks/zoom/', ...)`
|
|
- **Benefit**: Consistent API structure with proper versioning
|
|
|
|
#### Sync API Organization
|
|
- **Before**:
|
|
- `path('sync/task/<str:task_id>/status/', ...)`
|
|
- `path('sync/history/', ...)`
|
|
- **After**:
|
|
- `path('api/v1/sync/task/<str:task_id>/status/', ...)`
|
|
- `path('api/v1/sync/history/', ...)`
|
|
- **Benefit**: Sync endpoints properly categorized under API
|
|
|
|
### 2. Application URLs (`recruitment/urls.py`)
|
|
|
|
#### Application URL Consistency
|
|
- **Standardized Pattern**: `applications/<slug:slug>/[action]/`
|
|
- **Examples**:
|
|
- `applications/<slug:slug>/` (detail view)
|
|
- `applications/<slug:slug>/update/` (update view)
|
|
- `applications/<slug:slug>/delete/` (delete view)
|
|
- `applications/<slug:slug>/documents/upload/` (document upload)
|
|
|
|
#### Document Management URLs
|
|
- **Before**: Inconsistent patterns
|
|
- **After**: Consistent structure
|
|
- `applications/<slug:slug>/documents/upload/`
|
|
- `applications/<slug:slug>/documents/<int:document_id>/delete/`
|
|
- `applications/<slug:slug>/documents/<int:document_id>/download/`
|
|
|
|
#### Applicant Portal URLs
|
|
- **Standardized**: `applications/<slug:slug>/applicant-view/`
|
|
- **Benefit**: Clear separation between admin and applicant views
|
|
|
|
#### Removed Duplicates
|
|
- Eliminated duplicate `compose_application_email` URL
|
|
- Cleaned up commented-out URLs
|
|
- Removed inconsistent URL patterns
|
|
|
|
## URL Structure Standards
|
|
|
|
### 1. Naming Conventions
|
|
- **Snake Case**: All URL patterns use snake_case
|
|
- **Consistent Naming**: Related URLs share common prefixes
|
|
- **Descriptive Names**: URL names clearly indicate their purpose
|
|
|
|
### 2. Parameter Patterns
|
|
- **Slugs for SEO**: `<slug:slug>` for user-facing URLs
|
|
- **Integers for IDs**: `<int:pk>` or `<int:document_id>` for internal references
|
|
- **String Parameters**: `<str:task_id>` for non-numeric identifiers
|
|
|
|
### 3. RESTful Patterns
|
|
- **Collection URLs**: `/resource/` (plural)
|
|
- **Resource URLs**: `/resource/<id>/` (singular)
|
|
- **Action URLs**: `/resource/<id>/action/`
|
|
|
|
## API Structure
|
|
|
|
### Version 1 API Endpoints
|
|
```
|
|
/api/v1/
|
|
├── jobs/ # JobPosting ViewSet
|
|
├── candidates/ # Candidate ViewSet
|
|
├── templates/ # Form template management
|
|
│ ├── POST save/ # Save template
|
|
│ ├── GET <slug>/ # Load template
|
|
│ └── DELETE <slug>/ # Delete template
|
|
├── webhooks/
|
|
│ └── zoom/ # Zoom webhook endpoint
|
|
└── sync/
|
|
├── task/<id>/status/ # Sync task status
|
|
└── history/ # Sync history
|
|
```
|
|
|
|
## Frontend URL Organization
|
|
|
|
### 1. Core Dashboard & Navigation
|
|
```
|
|
/ # Dashboard
|
|
/login/ # Portal login
|
|
/careers/ # Public careers page
|
|
```
|
|
|
|
### 2. Job Management
|
|
```
|
|
/jobs/
|
|
├── <slug>/ # Job detail
|
|
├── create/ # Create new job
|
|
├── <slug>/update/ # Edit job
|
|
├── <slug>/upload-image/ # Upload job image
|
|
├── <slug>/applicants/ # Job applicants list
|
|
├── <slug>/applications/ # Job applications list
|
|
├── <slug>/calendar/ # Interview calendar
|
|
├── bank/ # Job bank
|
|
├── <slug>/post-to-linkedin/ # Post to LinkedIn
|
|
├── <slug>/edit_linkedin_post_content/ # Edit LinkedIn content
|
|
├── <slug>/staff-assignment/ # Staff assignment
|
|
├── <slug>/sync-hired-applications/ # Sync hired applications
|
|
├── <slug>/export/<stage>/csv/ # Export applications CSV
|
|
├── <slug>/request-download/ # Request CV download
|
|
├── <slug>/download-ready/ # Download ready CVs
|
|
├── <slug>/applications_screening_view/ # Screening stage view
|
|
├── <slug>/applications_exam_view/ # Exam stage view
|
|
├── <slug>/applications_interview_view/ # Interview stage view
|
|
├── <slug>/applications_document_review_view/ # Document review view
|
|
├── <slug>/applications_offer_view/ # Offer stage view
|
|
├── <slug>/applications_hired_view/ # Hired stage view
|
|
├── <slug>/application/<app_slug>/update_status/<stage>/<status>/ # Update status
|
|
├── <slug>/update_application_exam_status/ # Update exam status
|
|
├── <slug>/reschedule_meeting_for_application/ # Reschedule meeting
|
|
├── <slug>/schedule-interviews/ # Schedule interviews
|
|
├── <slug>/confirm-schedule-interviews/ # Confirm schedule
|
|
└── <slug>/applications/compose-email/ # Compose email
|
|
```
|
|
|
|
### 3. Application/Candidate Management
|
|
```
|
|
/applications/
|
|
├── <slug>/ # Application detail
|
|
├── create/ # Create new application
|
|
├── create/<job_slug>/ # Create for specific job
|
|
├── <slug>/update/ # Update application
|
|
├── <slug>/delete/ # Delete application
|
|
├── <slug>/resume-template/ # Resume template view
|
|
├── <slug>/update-stage/ # Update application stage
|
|
├── <slug>/retry-scoring/ # Retry AI scoring
|
|
├── <slug>/applicant-view/ # Applicant portal view
|
|
├── <slug>/documents/upload/ # Upload documents
|
|
├── <slug>/documents/<doc_id>/delete/ # Delete document
|
|
└── <slug>/documents/<doc_id>/download/ # Download document
|
|
```
|
|
|
|
### 4. Interview Management
|
|
```
|
|
/interviews/
|
|
├── <slug>/ # Interview detail
|
|
├── create/<app_slug>/ # Create interview (type selection)
|
|
├── create/<app_slug>/remote/ # Create remote interview
|
|
├── create/<app_slug>/onsite/ # Create onsite interview
|
|
├── <slug>/update_interview_status # Update interview status
|
|
├── <slug>/cancel_interview_for_application # Cancel interview
|
|
└── <job_slug>/get_interview_list # Get interview list for job
|
|
```
|
|
|
|
### 5. Person/Contact Management
|
|
```
|
|
/persons/
|
|
├── <slug>/ # Person detail
|
|
├── create/ # Create person
|
|
├── <slug>/update/ # Update person
|
|
└── <slug>/delete/ # Delete person
|
|
```
|
|
|
|
### 6. Training Management
|
|
```
|
|
/training/
|
|
├── <slug>/ # Training detail
|
|
├── create/ # Create training
|
|
├── <slug>/update/ # Update training
|
|
└── <slug>/delete/ # Delete training
|
|
```
|
|
|
|
### 7. Form & Template Management
|
|
```
|
|
/forms/
|
|
├── builder/ # Form builder
|
|
├── builder/<template_slug>/ # Form builder for template
|
|
├── create-template/ # Create form template
|
|
├── <template_id>/submissions/<slug>/ # Form submission details
|
|
├── template/<slug>/submissions/ # Template submissions
|
|
└── template/<template_id>/all-submissions/ # All submissions
|
|
|
|
/application/
|
|
├── signup/<template_slug>/ # Application signup
|
|
├── <template_slug>/ # Submit form
|
|
├── <template_slug>/submit/ # Submit action
|
|
├── <template_slug>/apply/ # Apply action
|
|
└── <template_slug>/success/ # Success page
|
|
```
|
|
|
|
### 8. Integration & External Services
|
|
```
|
|
/integration/erp/
|
|
├── / # ERP integration view
|
|
├── create-job/ # Create job via ERP
|
|
├── update-job/ # Update job via ERP
|
|
└── health/ # ERP health check
|
|
|
|
/jobs/linkedin/
|
|
├── login/ # LinkedIn login
|
|
└── callback/ # LinkedIn callback
|
|
|
|
/sources/
|
|
├── <pk>/ # Source detail
|
|
├── create/ # Create source
|
|
├── <pk>/update/ # Update source
|
|
├── <pk>/delete/ # Delete source
|
|
├── <pk>/generate-keys/ # Generate API keys
|
|
├── <pk>/toggle-status/ # Toggle source status
|
|
├── <pk>/test-connection/ # Test connection
|
|
└── api/copy-to-clipboard/ # Copy to clipboard
|
|
```
|
|
|
|
### 9. Agency & Portal Management
|
|
```
|
|
/agencies/
|
|
├── <slug>/ # Agency detail
|
|
├── create/ # Create agency
|
|
├── <slug>/update/ # Update agency
|
|
├── <slug>/delete/ # Delete agency
|
|
└── <slug>/applications/ # Agency applications
|
|
|
|
/agency-assignments/
|
|
├── <slug>/ # Assignment detail
|
|
├── create/ # Create assignment
|
|
├── <slug>/update/ # Update assignment
|
|
└── <slug>/extend-deadline/ # Extend deadline
|
|
|
|
/agency-access-links/
|
|
├── <slug>/ # Access link detail
|
|
├── create/ # Create access link
|
|
├── <slug>/deactivate/ # Deactivate link
|
|
└── <slug>/reactivate/ # Reactivate link
|
|
|
|
/portal/
|
|
├── dashboard/ # Agency portal dashboard
|
|
├── logout/ # Portal logout
|
|
├── <pk>/reset/ # Password reset
|
|
├── persons/ # Persons list
|
|
├── assignment/<slug>/ # Assignment detail
|
|
├── assignment/<slug>/submit-application/ # Submit application
|
|
└── submit-application/ # Submit application action
|
|
|
|
/applicant/
|
|
└── dashboard/ # Applicant portal dashboard
|
|
|
|
/portal/applications/
|
|
├── <app_id>/edit/ # Edit application
|
|
└── <app_id>/delete/ # Delete application
|
|
```
|
|
|
|
### 10. User & Account Management
|
|
```
|
|
/user/
|
|
├── <pk> # User detail
|
|
├── user_profile_image_update/<pk> # Update profile image
|
|
└── <pk>/password-reset/ # Password reset
|
|
|
|
/staff/
|
|
└── create # Create staff user
|
|
|
|
/set_staff_password/<pk>/ # Set staff password
|
|
/account_toggle_status/<pk> # Toggle account status
|
|
```
|
|
|
|
### 11. Communication & Messaging
|
|
```
|
|
/messages/
|
|
├── <message_id>/ # Message detail
|
|
├── create/ # Create message
|
|
├── <message_id>/reply/ # Reply to message
|
|
├── <message_id>/mark-read/ # Mark as read
|
|
├── <message_id>/mark-unread/ # Mark as unread
|
|
└── <message_id>/delete/ # Delete message
|
|
```
|
|
|
|
### 12. System & Administrative
|
|
```
|
|
/settings/
|
|
├── <pk>/ # Settings detail
|
|
├── create/ # Create settings
|
|
├── <pk>/update/ # Update settings
|
|
├── <pk>/delete/ # Delete settings
|
|
└── <pk>/toggle/ # Toggle settings
|
|
|
|
/easy_logs/ # Easy logs view
|
|
|
|
/note/
|
|
├── <slug>/application_add_note/ # Add application note
|
|
├── <slug>/interview_add_note/ # Add interview note
|
|
└── <slug>/delete/ # Delete note
|
|
```
|
|
|
|
### 13. Document Management
|
|
```
|
|
/documents/
|
|
├── upload/<slug>/ # Upload document
|
|
├── <doc_id>/delete/ # Delete document
|
|
└── <doc_id>/download/ # Download document
|
|
```
|
|
|
|
### 14. API Endpoints
|
|
```
|
|
/api/
|
|
├── create/ # Create job API
|
|
├── <slug>/edit/ # Edit job API
|
|
├── application/<app_id>/ # Application detail API
|
|
├── unread-count/ # Unread count API
|
|
|
|
/htmx/
|
|
├── <pk>/application_criteria_view/ # Application criteria view
|
|
├── <slug>/application_set_exam_date/ # Set exam date
|
|
└── <slug>/application_update_status/ # Update status
|
|
```
|
|
|
|
## Benefits of Improvements
|
|
|
|
### 1. Maintainability
|
|
- **Consistent Patterns**: Easier to understand and modify
|
|
- **Clear Organization**: Related URLs grouped together
|
|
- **Reduced Duplication**: Eliminated redundant URL definitions
|
|
|
|
### 2. Scalability
|
|
- **API Versioning**: Ready for future API changes
|
|
- **Modular Structure**: Easy to add new endpoints
|
|
- **RESTful Design**: Follows industry standards
|
|
|
|
### 3. Developer Experience
|
|
- **Predictable URLs**: Easy to guess URL patterns
|
|
- **Clear Naming**: URL names indicate their purpose
|
|
- **Better Documentation**: Structure is self-documenting
|
|
|
|
### 4. SEO and User Experience
|
|
- **Clean URLs**: User-friendly and SEO-optimized
|
|
- **Consistent Patterns**: Users can navigate intuitively
|
|
- **Clear Separation**: Admin vs. user-facing URLs
|
|
|
|
## Migration Guide
|
|
|
|
### For Developers
|
|
1. **Update API Calls**: Change `/api/` to `/api/v1/`
|
|
2. **Update Sync URLs**: Move sync endpoints to `/api/v1/sync/`
|
|
3. **Update Template References**: Use new URL names in templates
|
|
|
|
### For Frontend Code
|
|
1. **JavaScript Updates**: Update AJAX calls to use new API endpoints
|
|
2. **Template Updates**: Use new URL patterns in Django templates
|
|
3. **Form Actions**: Update form actions to use new URLs
|
|
|
|
## Future Considerations
|
|
|
|
### 1. API v2 Planning
|
|
- Structure is ready for API v2 implementation
|
|
- Can maintain backward compatibility with v1
|
|
|
|
### 2. Additional Endpoints
|
|
- Easy to add new endpoints following established patterns
|
|
- Consistent structure makes expansion straightforward
|
|
|
|
### 3. Authentication
|
|
- API structure ready for token-based authentication
|
|
- Clear separation of public and private endpoints
|
|
|
|
## Testing Recommendations
|
|
|
|
### 1. URL Resolution Tests
|
|
- Test all new URL patterns resolve correctly
|
|
- Verify reverse URL lookups work
|
|
|
|
### 2. API Endpoint Tests
|
|
- Test API v1 endpoints respond correctly
|
|
- Verify versioning doesn't break existing functionality
|
|
|
|
### 3. Integration Tests
|
|
- Test frontend templates with new URLs
|
|
- Verify JavaScript AJAX calls work with new endpoints
|
|
|
|
## Conclusion
|
|
|
|
These URL structure improvements provide a solid foundation for the ATS application's continued development and maintenance. The consistent, well-organized structure will make future enhancements easier and improve the overall developer experience.
|