add/fix: small changes on docs and comment style

core/apps/accounts/urls.py

@@ -4,24 +4,16 @@ Accounts app urls
 
 from django.urls import path, include
 from rest_framework_simplejwt import views as jwt_views
-from .views import (
+from . import views
-    RegisterView, 
-    ResetPasswordView, 
-    MeView, 
-    ChangePasswordView, 
-    MeCompanyView,
-)
 from rest_framework.routers import DefaultRouter  # type: ignore
 
 
 router = DefaultRouter()
-router.register("auth", RegisterView, basename="auth")  # type: ignore
-router.register("auth", ResetPasswordView, basename="reset-password")  # type: ignore
-router.register("auth", MeView, basename="me")  # type: ignore
-router.register("auth", ChangePasswordView, basename="change-password")  # type: ignore
-
-router.register(r"me/companies", MeCompanyView, "me-company")  # type: ignore
 
+router.register("auth", views.RegisterView, basename="auth")  # type: ignore
+router.register("auth", views.ResetPasswordView, basename="reset-password")  # type: ignore
+router.register("auth", views.MeView, basename="me")  # type: ignore
+router.register("auth", views.ChangePasswordView, basename="change-password")  # type: ignore
 
 urlpatterns = [  # type: ignore
     path("", include(router.urls)),  # type: ignore
@@ -32,4 +24,14 @@ urlpatterns = [  # type: ignore
         jwt_views.TokenRefreshView.as_view(),
         name="token_refresh",
     ),
+    path(
+        r"users/<uuid:pk>/companies",
+        views.UserCompanyApiView.as_view(),
+        name="user-company-api-view"
+    ),
+    path(
+        r"me/companies",
+        views.MeCompanyApiView.as_view(),
+        name="me-company-api-view"
+    )
 ]

core/apps/accounts/views/me.py

@@ -1,4 +1,4 @@
-from rest_framework.viewsets import GenericViewSet  # type: ignore
+from rest_framework.generics import GenericAPIView  # type: ignore
 from rest_framework.decorators import action  # type: ignore
 from rest_framework import status  # type: ignore
 from rest_framework.request import HttpRequest  # type: ignore
@@ -7,8 +7,7 @@ from rest_framework.permissions import (  # type: ignore
     IsAuthenticated
 )
 
-from django_core.mixins import BaseViewSetMixin  # type: ignore
+from core.utils.views import BaseApiViewMixin
-
 from core.apps.companies.serializers import (
     RetrieveCompanySerializer,
     CreateCompanySerializer,
@@ -21,50 +20,29 @@ from core.apps.companies.models import (
 from django.db import transaction
 
 
-class MeCompanyView(BaseViewSetMixin, GenericViewSet):
+######################################################################
+# @api-view  |  POST, GET - me/companies
+######################################################################
+class MeCompanyApiView(BaseApiViewMixin, GenericAPIView):  # type: ignore
     permission_classes = [IsAuthenticated]
 
-    action_permission_classes = {}
+    method_permission_classes = {}
-    action_serializer_class = {
+    method_serializer_class = {
-        "create": CreateCompanySerializer,
+        "post": CreateCompanySerializer,
-        "list": RetrieveCompanySerializer,
+        "get": RetrieveCompanySerializer,
     }
 
-    def list(
+    def get(self, request: HttpRequest, *args: object, **kwargs: object) -> Response:
-        self,
+        companies = CompanyModel.objects.filter(accounts__user=request.user)
-        request: HttpRequest,
+        ser = RetrieveCompanySerializer(instance=companies, many=True)
-        *args: object,
+        return Response(ser.data, status.HTTP_200_OK)
-        **kwargs: object
-    ) -> Response:
-        
-        companies = CompanyModel.objects.filter(
-            accounts__user=request.user
-        )
-
-        return Response(
-            RetrieveCompanySerializer(instance=companies, many=True).data, 
-            status=status.HTTP_200_OK
-        )
     
-    def create(
+    def create(self, request: HttpRequest, *args: object, **kwargs: object) -> Response:
-        self,
-        request: HttpRequest,
-        *args: object,
-        **kwargs: object
-    ) -> Response:
-        
         with transaction.atomic():
             serializer = CreateCompanySerializer(data=request.data)  # type: ignore
             serializer.is_valid(raise_exception=True)
             company = serializer.save()  # type: ignore
 
-            account = CompanyAccountModel(
+            account = CompanyAccountModel(company=company, user=request.user)
-                company=company, 
-                user=request.user
-            )
             account.save()
-
+        return Response(serializer.data, status.HTTP_201_CREATED)
-        return Response(
-            data=serializer.data, 
-            status=status.HTTP_201_CREATED
-        )

core/apps/accounts/views/users.py

@@ -2,24 +2,25 @@ import uuid
 
 from drf_spectacular.utils import extend_schema
 
-from rest_framework.viewsets import GenericViewSet  # type: ignore
+from rest_framework.generics import GenericAPIView  # type: ignore
 from rest_framework.decorators import action  # type: ignore
+from rest_framework.permissions import IsAdminUser
 from rest_framework import status  # type: ignore
 from rest_framework.request import HttpRequest  # type: ignore
 from rest_framework.response import Response  # type: ignore
 from rest_framework.permissions import (  # type: ignore
     IsAdminUser,
 )
-from django_core.mixins import BaseViewSetMixin
 
 from rest_framework.generics import get_object_or_404  # type: ignore
 from django.contrib.auth import get_user_model
 from django.db import transaction
 
-
+from core.utils.views import BaseApiViewMixin
 from core.apps.companies.serializers import (
     CreateCompanySerializer,
-    RetrieveCompanySerializer
+    RetrieveCompanySerializer,
+    BaseCompanySerializer,
 )
 from core.apps.companies.models import (
     CompanyModel,
@@ -29,47 +30,53 @@ from core.apps.companies.models import (
 UserModel = get_user_model()
 
 
-class UserCompaniesView(BaseViewSetMixin, GenericViewSet):
+######################################################################
+# /users/{id}/companies
+######################################################################
+@extend_schema(tags=["User Companies"])
+class UserCompanyApiView(BaseApiViewMixin, GenericAPIView):  # type: ignore
+    queryset = UserModel.objects.all()
     permission_classes = [IsAdminUser]
+    serializer_class = BaseCompanySerializer
 
-    action_permission_classes = {}
+    method_permission_classes = {
-    action_permission_classes = {
+        "get": [IsAdminUser],
-        "list_company": RetrieveCompanySerializer,
+        "post": [IsAdminUser],
-        "create_company": CreateCompanySerializer,
+    }
+    method_serializer_class = {
+        "get": RetrieveCompanySerializer,
+        "post": CreateCompanySerializer,
     }
 
     @extend_schema(
-        summary="Get list of companies",
+        summary="Get List Of Companies For User",
-        description="Get list of companies",
+        description="Get List Of Companies For User",
     )
-    @action(url_path="companies", detail=True, methods=["GET"])
+    def get(
-    def list_company(
         self,
         request: HttpRequest,
         pk: uuid.UUID,
         *args: object,
         **kwargs: object,
     ) -> Response:
-        
         companies = CompanyModel.objects.filter(accounts__user__pk=pk)
         return Response(
             data=RetrieveCompanySerializer(instance=companies, many=True),
             status=status.HTTP_200_OK
         )
-    
+
+
     @extend_schema(
-        summary="Create Company",
+        summary="Create Company For User",
-        description="Create Company",
+        description="Create Company For User",
     )
-    @action(url_path="companies", detail=True, methods=["POST"])
+    def post(
-    def create_company(
         self,
         request: HttpRequest,
         pk: uuid.UUID,
         *args: object,
         **kwargs: object,
     ) -> Response:
-
         with transaction.atomic():
             ser = CreateCompanySerializer(data=request.data)  # type: ignore
             ser.is_valid(raise_exception=True)
@@ -81,4 +88,3 @@ class UserCompaniesView(BaseViewSetMixin, GenericViewSet):
             account.save()
 
         return Response(data=ser.data, status=status.HTTP_201_CREATED)
-    

core/apps/companies/views/folders.py

@@ -51,6 +51,7 @@ class CompanyFolderCrudViewSet(BaseViewSetMixin, ModelViewSet):
 ######################################################################
 # /company-folders/<uuid:pk>/contracts
 ######################################################################
+@extend_schema(tags=["CompanyFolder Contracts"])
 class ContractFolderApiView(BaseApiViewMixin, GenericAPIView):  # type: ignore
     queryset = CompanyFolderModel.objects.all()
     permission_classes = [IsFolderOwner]

docs/COMMENTS.md

@@ -0,0 +1,96 @@
+## 🚀 View Commenting Convention for Fast Debugging & Navigation
+
+To streamline debugging and code navigation, every view class should be preceded by a **clearly structured comment block**. This format makes it easy to:
+
+* Quickly locate views by endpoint path or method
+* Search views by type (`APIView`, `ViewSet`) via CLI tools like `rg` or `grep`
+* Immediately understand what a view is responsible for
+
+---
+
+### ✅ Format
+
+```python
+###################################################################################
+# @<view-type>  |  <METHODS IN UPPERCASE> - <endpoint path>
+###################################################################################
+```
+
+#### Example:
+
+```python
+###################################################################################
+# @api-view  |  POST, GET - /me/companies
+###################################################################################
+class MeCompanyApiView(GenericAPIView):
+    ...
+```
+
+---
+
+### 🔎 Field Reference
+
+| Field             | Purpose                                                             | Example                        |
+| ----------------- | ------------------------------------------------------------------- | ------------------------------ |
+| `@<view-type>`    | Declares the kind of view used — aids CLI-based filtering/searching | `@api-view`, `@view-set`       |
+| `<METHODS>`       | HTTP methods the view handles                                       | `GET`, `POST`, `PUT`, etc.     |
+| `<endpoint path>` | The URL route where the view is mounted                             | `/users/files/<int:pk>/upload` |
+
+---
+
+### 📘 View Types
+
+Use one of the following view-type identifiers:
+
+| Type        | Description                                                        |
+| ----------- | ------------------------------------------------------------------ |
+| `@api-view` | For views that inherit from `GenericAPIView` or `APIView`          |
+| `@view-set` | For views that inherit from `GenericViewSet`, `ModelViewSet`, etc. |
+
+---
+
+### ♻️ HTTP Methods
+
+List only the HTTP methods the view explicitly supports:
+
+* `GET`
+* `POST`
+* `PUT`
+* `PATCH`
+* `DELETE`
+* `OPTIONS`
+
+Order doesn't matter, but use **uppercase** for consistency.
+
+---
+
+### 📍 Endpoint Path
+
+This should reflect the actual route where the view is registered.
+
+Use Django/DRF-style parameters:
+
+```text
+/users/<uuid:pk>/folders/
+/files/<int:file_id>/download/
+/me/companies/
+```
+
+---
+
+### 🚧 Best Practices
+
+* Use this comment format **before every `GenericAPIView`, `ViewSet`, or similar**.
+* Avoid including permissions, descriptions, or extra metadata unless necessary.
+* Keep comments strictly scoped to navigation/debugging.
+* Use CLI tools to search:
+
+  ```bash
+  rg "@api-view"
+  rg "companies"
+  rg "POST, GET"
+  ```
+
+---
+
+This pattern ensures developers can **lightning-fast locate views**, trace bugs, and maintain high code readability in large DRF codebases.

docs/ENDPOINTS.md

@@ -0,0 +1,175 @@
+## 📌 API Endpoint Overview
+
+This document provides a categorized and role-specific overview of all API endpoints implemented (or to be implemented) in the system. It is structured for easy readability, regular updates, and fast navigation.
+
+---
+
+### ⚖️ Roles
+
+* `admin` — Endpoints accessible only to admins.
+* `user`  — Endpoints accessible to regular authenticated users.
+
+> Status Legend:
+>
+> * `ok`       — Fully implemented and tested
+> * `partial`  — Implemented but incomplete or unstable
+> * `TODO`     — Needs implementation
+> * `not ok`   — Implemented but incorrect or buggy
+
+---
+
+## 🔑 Auth & Users
+
+#### users:
+
+* `POST /auth/register`                         — user   — remake
+* `POST /auth/verify`                           — user   — ok
+* `GET /auth/me`                                — user   — ok
+
+#### me/companies:
+
+* `GET /me/companies`                           — user   — ok
+* `POST /me/companies`                          — user   — ok
+
+#### users/<uuid>:
+
+* `GET /users/<uuid:pk>/companies`             — user   — ok
+* `POST /users/<uuid:pk>/companies`            — user   — ok
+
+---
+
+## 🏢 Companies
+
+#### companies:
+
+* `GET /companies`                              — admin  — ok
+
+* `POST /companies`                             — admin  — ok
+
+* `GET /companies/<uuid:pk>`                    — admin  — ok
+
+* `DELETE /companies/<uuid:pk>`                 — admin  — ok
+
+* `PATCH /companies/<uuid:pk>`                  — admin  — ok
+
+* `GET /companies/<uuid:pk>/contracts`          — user   — partial
+
+  * filters: `folder`, `status: list[str]`
+
+* `GET /companies/<uuid:pk>/folders`            — user   — ok
+
+* `POST /companies/<uuid:pk>/folders`           — user   — ok
+
+* `GET /companies/<uuid:pk>/accounts`           — user   — ok
+
+* `POST /companies/<uuid:pk>/accounts`          — user   — TODO
+
+---
+
+## 💳 Company Accounts
+
+* `GET /company-accounts`                       — admin  — ok
+
+* `POST /company-accounts`                      — admin  — ok
+
+* `GET /company-accounts/<uuid:pk>`             — admin  — ok
+
+* `PATCH /company-accounts/<uuid:pk>`           — admin  — ok
+
+* `DELETE /company-accounts/<uuid:pk>`          — admin  — ok
+
+* `POST /accounts/verify`                       — user   — TODO
+
+  * required: `phone`, `code`
+
+---
+
+## 🌐 Banks
+
+* `GET /banks`                                   — admin  — ok
+* `POST /banks`                                  — admin  — ok
+* `GET /banks/<uuid:pk>`                         — admin  — ok
+* `DELETE /banks/<uuid:pk>`                      — admin  — ok
+* `PATCH /banks/<uuid:pk>`                       — admin  — ok
+
+---
+
+## 📍 Contracts
+
+* `GET /contracts`                               — admin  — ok
+
+* `POST /contracts`                              — user   — ok
+
+* `GET /contracts/<uuid:pk>`                     — admin  — ok
+
+* `DELETE /contracts/<uuid:pk>`                  — admin  — ok
+
+* `PATCH /contracts/<uuid:pk>`                   — admin  — ok
+
+* `GET /contracts/<uuid:pk>/files`               — user   — ok
+
+* `GET /contracts/<uuid:pk>/owners`              — user   — ok
+
+---
+
+## 📄 Contract Owners
+
+* `GET /contract-owners`                         — admin  — ok
+
+* `POST /contract-owners`                        — admin  — ok
+
+* `GET /contract-owners/<uuid:pk>`               — admin  — ok
+
+* `DELETE /contract-owners/<uuid:pk>`            — admin  — ok
+
+* `PATCH /contract-owners/<uuid:pk>`             — admin  — ok
+
+* `GET /contract-owners/<uuid:pk>/contract`      — user   — ok
+
+* `POST /contract-owners/<uuid:pk>/files`        — user   — not ok
+
+* `GET /contract-owners/<uuid:pk>/files`         — user   — not ok
+
+* `DELETE /contract-owners/<uuid:pk>/files/<uuid:pk>` — user — ok
+
+* `POST /contract-owners/<uuid:pk>/files/<uuid:pk>/upload` — user — ok
+
+---
+
+## 📂 Files
+
+* `GET /files`                                   — admin  — ok
+* `POST /files`                                  — admin  — ok
+* `GET /files/<uuid:pk>`                         — admin  — ok
+* `DELETE /files/<uuid:pk>`                      — admin  — ok
+* `PATCH /files/<uuid:pk>`                       — admin  — ok
+
+---
+
+## 📁 Folders
+
+* `GET /folders`                                 — admin  — ok
+
+* `POST /folders`                                — admin  — ok
+
+* `GET /folders/<uuid:pk>`                       — admin  — ok
+
+* `DELETE /folders/<uuid:pk>`                    — admin  — ok
+
+* `PATCH /folders/<uuid:pk>`                     — admin  — ok
+
+* `GET /folders/<uuid:pk>/contracts`             — admin  — ok
+
+---
+
+## 📋 File Contents
+
+* `GET /file-contents`                           — admin  — ok
+* `POST /file-contents`                          — admin  — ok
+* `GET /file-contents/<uuid:pk>`                 — admin  — ok
+* `DELETE /file-contents/<uuid:pk>`              — admin  — ok
+* `PATCH /file-contents/<uuid:pk>`               — admin  — ok
+
+---
+
+This structure ensures developers can **navigate quickly**, **see responsibilities by domain**, and easily **track implementation status**. Update it regularly as your API evolves.