sequenceDiagram autonumber participant Browser participant Middleware as Middleware (auth:sanctum) participant Ctrl as FileController participant Svc as FileService participant Checker as FilePermissionChecker participant Repo as FileRepository participant DB as MySQL (mdldf_*) participant Storage as MoodleFileStorage Browser->>Middleware: GET /api/v1/files/{id}/content Middleware->>Middleware: Verify Sanctum token Middleware->>Middleware: Check moodle.active (user not deleted/suspended) Middleware->>Ctrl: Authenticated request Ctrl->>Svc: stream(FileShowDTO{fileId, studentId}) Svc->>Repo: findById(fileId) Repo->>DB: SELECT * FROM files WHERE id=? AND filename != '.' DB-->>Repo: MoodleFile row Repo-->>Svc: MoodleFile model Svc->>Checker: checkRead(file, studentId) Checker->>DB: SELECT contextlevel, instanceid FROM context WHERE id=? DB-->>Checker: context row alt Context = Course (level 50) Checker->>DB: JOIN user_enrolments ON enrol WHERE courseid=? AND userid=? AND status=active DB-->>Checker: enrolled row (or empty) else Context = Module (level 70) Checker->>DB: SELECT course, visible FROM course_modules WHERE id=? DB-->>Checker: module row Checker->>DB: enrollment check (same as Course) DB-->>Checker: enrolled row (or empty) else Context = User (level 30) Checker->>Checker: file.userid === studentId ? else Context = System / Category / Block Checker->>Checker: pass (authenticated only) end alt Access denied Checker-->>Svc: throw FileAccessDeniedException Svc-->>Ctrl: exception propagates Ctrl-->>Browser: 404 JSON (hides file existence) end Checker-->>Svc: void (access granted) Svc->>Storage: readStream(contenthash) Storage->>Storage: pathFor(hash) → "ab/cd/abcdef..." Storage->>Storage: disk().readStream(path) alt File missing from disk Storage-->>Svc: throw FileStorageException Svc-->>Ctrl: exception propagates Ctrl-->>Browser: 500 JSON (storage error) end Storage-->>Svc: resource (stream handle) Svc-->>Ctrl: FileStreamDTO{stream, mimetype, filesize, filename} Ctrl-->>Browser: 200 StreamedResponse (Content-Type + Content-Disposition headers)

sequenceDiagram autonumber participant Browser participant Middleware as Middleware participant Req as UploadFileRequest participant Ctrl as FileController participant Svc as FileService participant Repo as FileRepository participant Storage as MoodleFileStorage participant DB as MySQL (mdldf_files) participant Disk as Disk (local/S3) Browser->>Middleware: POST /api/v1/files (multipart) Middleware-->>Req: validated request Req->>Req: validate(file, context_id, component, filearea, item_id) alt Validation fails Req-->>Browser: 422 Unprocessable Entity end Req->>Ctrl: toDTO() → UploadFileDTO Ctrl->>Svc: upload(UploadFileDTO) Svc->>Svc: sha1_file(tmpPath) → contenthash Svc->>Svc: sha1("/{contextId}/...") → pathnamehash Svc->>Storage: exists(contenthash)? Storage->>Disk: disk().exists(ab/cd/contenthash) Disk-->>Storage: bool alt Content not yet on disk Svc->>Storage: put(contenthash, stream) Storage->>Disk: disk().writeStream(path, stream) end Svc->>Repo: insert(attributes) Repo->>DB: DB::table('files')->insertGetId({...}) DB-->>Repo: new file ID Repo-->>Svc: int id Svc->>Repo: findById(id) Repo->>DB: SELECT * FROM files WHERE id=? DB-->>Repo: MoodleFile row Repo-->>Svc: MoodleFile Svc-->>Ctrl: MoodleFile Ctrl-->>Browser: 201 Created + FileResource JSON

flowchart TD A([HTTP Request to /api/v1/files/*]) --> B{auth:sanctum
token valid?} B -- No --> B1[401 Unauthenticated] B -- Yes --> C{moodle.active
user active?} C -- No --> C1[403 Forbidden] C -- Yes --> D{Which endpoint?} D --> E1["GET /context/{contextId}
list files"] D --> E2["GET /{id}
show metadata"] D --> E3["GET /{id}/content
stream bytes"] D --> E4["POST /
upload file"] E1 --> F1[ListFilesRequest validates
component, filearea, per_page] F1 --> G1[FileService.list
FileRepository.listByContext] G1 --> H1[Paginated query
filename != '.'] H1 --> I1[200 FileResource collection] E2 --> F2[FileRepository.findById] F2 --> F2a{File exists?} F2a -- No --> ERR404[404 Not Found] F2a -- Yes --> F2b[FilePermissionChecker.checkRead] F2b --> PERM{Permission
check} E3 --> G3[FileService.stream → show first] G3 --> F2a PERM --> PERM1{Context level?} PERM1 -- System 10 / Category 40 / Block 80 --> PASS[✅ Pass] PERM1 -- User 30 --> PERM2{file.userid
== studentId?} PERM2 -- No --> ERR404 PERM2 -- Yes --> PASS PERM1 -- Course 50 --> PERM3{Active
enrollment?} PERM3 -- No --> ERR404 PERM3 -- Yes --> PASS PERM1 -- Module 70 --> PERM4{module.visible
== true?} PERM4 -- No --> ERR404 PERM4 -- Yes --> PERM3 PERM1 -- Unknown --> ERR404 PASS --> SHOW_END[200 FileResource JSON] PASS --> STREAM{Endpoint = stream?} STREAM -- Yes --> S1[MoodleFileStorage.readStream
ab/cd/hash path] S1 --> S2{File on
disk?} S2 -- No --> ERR500[500 Storage Error] S2 -- Yes --> S3[200 StreamedResponse
Content-Type / Content-Disposition] E4 --> V1[UploadFileRequest validates
file, context_id, component, filearea, item_id] V1 --> V1a{Valid?} V1a -- No --> ERR422[422 Validation Error] V1a -- Yes --> U1[sha1_file → contenthash
sha1 path → pathnamehash] U1 --> U2{contenthash
on disk?} U2 -- No --> U3[MoodleFileStorage.put
writeStream to disk] U2 -- Yes --> U4 U3 --> U4[FileRepository.insert
DB::table files insertGetId] U4 --> U5[findById → MoodleFile] U5 --> U6[201 Created + FileResource JSON] style B1 fill:#ef4444,color:#fff,stroke:none style C1 fill:#ef4444,color:#fff,stroke:none style ERR404 fill:#ef4444,color:#fff,stroke:none style ERR500 fill:#ef4444,color:#fff,stroke:none style ERR422 fill:#f59e0b,color:#000,stroke:none style I1 fill:#10b981,color:#fff,stroke:none style SHOW_END fill:#10b981,color:#fff,stroke:none style S3 fill:#10b981,color:#fff,stroke:none style U6 fill:#10b981,color:#fff,stroke:none