marwan/kaauh_ats
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kaauh_ats/URL_STRUCTURE_IMPROVEMENTS.md
ismail f2e202ec1a cleanup
2025-12-10 13:56:51 +03:00

14 KiB
Raw Permalink Blame History

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.