When a team is asked to “quickly build a submission portal,” it sounds easy at first. You might think it will take just a couple of sprints. But once you start working on it, things get complicated.
Handling file uploads in real life is not simple. You have to deal with big files like 300MB ZIPs, broken PDFs, security checks, different browsers, and students submitting right before the deadline. Because of this, a two-week project can turn into a six-week project.
The basic features, like user roles, assignments, and grading, are actually pretty simple. The real problem is managing files properly.
This guide is for engineering leaders who want to avoid this situation. Instead of building file handling from scratch, you can use ready-made file services through APIs. That way, you can launch a complete and reliable submission portal in days instead of weeks.
Key Takeaways
File handling is the hardest part of a submission portal, not basic CRUD features.
Keep your core app logic separate from file handling to build faster.
Use APIs for uploads, processing, and security instead of building everything yourself.
Automate virus scanning, file checks, and conversions using workflows and webhooks.
Spend your engineering time on features that make your product unique, not on managing file systems.
Why “Just Build It” Costs More Than You Think
Before talking about architecture, let’s be honest about the real scope. A good submission portal has two main parts, and they’re not equally difficult.
Part one: users, roles, assignments, and grades.
This is predictable work. Your team has built CRUD apps before. The database structure is clear, edge cases are manageable, and you can estimate the effort.
Part two: file handling.
This is where the hidden effort shows up.
A production-ready file system needs much more than a simple upload button. For example:
A drag-and-drop uploader that works on all browsers and devices.
Support for large files using chunked uploads (so uploads don’t fail if the network drops).
Virus scanning before files are stored.
Automatic file format checks (because someone will upload the wrong format).
Converting documents to PDF for consistent grading.
Secure, time-limited access links for graders.
CDN delivery for fast access.
Storage that scales automatically.
Each of these is a project on its own.
Here’s how custom building compares with using an API:
ComponentBuild from ScratchUse APIMain Risk ReducedDrag-and-drop upload UI2–3 weeks< 1 hourBrowser issues, accessibility problemsLarge & multi-file uploads1–2 weeksSimple setupNetwork failures, large file handlingVirus scanning & securityOngoing maintenanceIncludedMalware, security vulnerabilitiesFile processing (PDF conversion, image optimisation)1+ week per formatOn-demandLibrary maintenance, format supportCDN delivery1–2 weeksIncludedSlow loading, scaling problems
So this choice isn’t really about whether your team can build it. It’s about whether they should spend time building it.
Your engineers’ time is valuable. It’s better spent creating features that make your portal stand out and be useful, not rebuilding file systems and tools that are already available and reliable.
So if file handling is where most of the hidden complexity lives, the real question becomes: how should we design the system differently?
The Architecture That Enables Speed
Teams that ship fast follow one simple idea: clearly separate your main application logic from file handling. Then let a specialised API take care of everything related to files.
Here’s what that looks like in practice:
Think in three simple layers:
Frontend: The interface where students submit work and graders review it.
Business logic: The rules for deadlines, submissions, grading, and permissions.
Data model: The database structure: users, assignments, submissions, and grades.
Your team focuses only on these three layers.
From the moment a student clicks “Submit” until a grader opens the file, everything related to the file itself, uploading, storing, scanning for security, and processing, is handled by a file service like Filestack.
By keeping file handling separate, your system stays cleaner, quicker to build, and much easier to maintain.
Once you separate business logic from file handling, the implementation becomes much simpler.
Implementation: The Three Accelerators
At this point, the goal is simple: turn weeks of work into just a few days by focusing only on the parts that make your portal unique.
These three accelerators remove the biggest slowdowns: file uploading, file processing, and file delivery, so your team can build faster without compromising on quality or security.
1. The Upload Experience
The submission form is the most important user-facing part of your portal. It’s also where front-end complexity grows quickly if you build everything yourself.
Supporting Google Drive, OneDrive, Dropbox, and local uploads, while keeping drag-and-drop smooth, showing upload progress, and making it work across browsers, is a serious frontend effort.
Embedding Filestack’s File Picker reduces this to a few hours of integration work.
Here’s what it looks like in a React submission form:
import React, { useState } from "react";
import * as filestack from "filestack-js";
const client = filestack.init("YOUR_API_KEY_HERE");
function FilestackUpload() {
const [fileData, setFileData] = useState(null);
const handleUpload = async () => {
try {
const result = await client.picker({
accept: ["image/*"],
maxFiles: 1,
maxSize: 5 * 1024 * 1024,
onUploadDone: (res) => {
console.log("Upload done:", res);
setFileData(res.filesUploaded[0]);
},
}).open();
} catch (error) {
console.error("Upload failed:", error);
}
};
return (
<div>
<button onClick={handleUpload}>Upload File</button>
{fileData && (
<div style={{ marginTop: "20px" }}>
<p>File uploaded: {fileData.filename}</p>
<img src={fileData.url} alt="Uploaded" style={{ maxWidth: "300px" }} />
</div>
)}
</div>
);
}
export default FilestackUpload;
Out of the box, students get:
Multi-file upload
Cloud storage support
Upload progress indicators
Built-in error handling
All is maintained by a team focused entirely on making file uploads reliable.
Building a great drag-and-drop experience from scratch is more complex than it looks. By integrating a ready-made solution, you get a polished upload system without spending weeks developing and maintaining it yourself.
Uploading is just the first step. Once files are in the system, they need to be secured and processed automatically.
2. The Security and Processing Pipeline
Every file a student uploads is unknown and could be risky. In a real production system with hundreds or thousands of users, virus scanning isn’t optional; it’s necessary.
Also, checking only the file extension isn’t enough. A file called assignment.pdf might not actually be a real PDF. You need proper file validation.
Beyond security, there’s another issue: different file formats.
Students upload:
Images in JPEG, PNG, HEIF, WebP
Documents in .docx, .pages, or scanned PDFs
If graders have to deal with all these different formats, it slows them down. That extra friction comes from the system design.
A better approach is to automatically process every file as soon as it’s uploaded.
With Filestack’s Workflows API, you can set up an automatic pipeline that:
Scans files for viruses
Validates file types
Converts documents to PDF
Compresses large images
Optimises files for storage and delivery
All of this happens automatically after upload. You don’t need to write custom code for each file type.
If you want to explore this further, orchestrating automated file processing workflows explains the full setup in detail and walks through how to configure these pipelines properly.
Security is especially important. If you manage virus scanning yourself, you’re responsible for:
Updating virus definitions
Maintaining scanning systems
Handling false positives
Monitoring security vulnerabilities
That’s ongoing work your team has to handle forever.
By using a file API that includes built-in security and processing, your team avoids long-term maintenance and keeps the system safer with far less effort.
Comprehensive security measures for uploads are built directly into the API layer, removing a long-term maintenance burden your team would otherwise have to manage on its own.
With processing handled automatically, the final piece is connecting everything back to your grading workflow.
3. Webhooks and the Grading Workflow
This is where the architecture really shows its value.
When a student submits a file, you don’t want to pause everything while virus scanning and file conversion finish. Instead, you accept the submission immediately, let Filestack process the file in the background, and wait to be notified when it’s ready.
That notification happens through a webhook.
Your backend provides a special endpoint that Filestack automatically calls after the file has been scanned, validated, and processed.
# Flask example
@app.route('/webhooks/filestack', methods=['POST'])
def handle_filestack_webhook():
payload = request.json
if payload['action'] == 'fp.upload':
file_handle = payload['data']['url'].split('/')[-1]
submission_id = payload['metadata']['submission_id']
# Update submission status in your database
db.submissions.update(
{'_id': submission_id},
{'$set': {
'status': 'processed',
'file_handle': file_handle,
'ready_for_grading': True
}}
)
# Trigger your grading notification
notify_grader(submission_id)
return jsonify({'status': 'ok'})
Here’s what happens step by step:
A student uploads a file.
The system accepts the submission immediately.
Filestack processes the file in the background (scan, convert, optimise).
Once processing is complete, Filestack sends a webhook request to your backend.
Your backend updates the submission status and notifies the grader.
Now the file is marked as ready and can be safely accessed.
This pattern keeps your system fast and responsive while heavy processing runs separately.
If you want to understand how this pattern applies more broadly, leveraging webhooks for automation shows how webhooks can automate workflows across many engineering use cases, not just submission portals.
Secure Grader Access
Graders should not receive public, permanent links to student submissions. Files should only be accessible for a limited time and only to authorised users.
Filestack supports time-limited, policy-based access links. That means you can generate a secure URL that works for a short period, like one hour, and then automatically expires.
Here’s a simple example:
const generateSecureGraderLink = (fileHandle, graderId) => {
const policy = {
expiry: Math.floor(Date.now() / 1000) + 3600, // 1-hour access
handle: fileHandle,
call: ['read'],
};
const encodedPolicy = btoa(JSON.stringify(policy));
const signature = hmacSha256(encodedPolicy, YOUR_APP_SECRET);
return `https://cdn.filestackcontent.com/${fileHandle}` +
`?policy=${encodedPolicy}&signature=${signature}`;
};
What this does:
Creates a policy that allows read access.
Sets an expiry time (1 hour in this case).
Sign the request securely using your app secret.
Generates a temporary access link.
The grader gets a link that works for one hour. After that, it automatically stops working.
This prevents permanent public access to submissions and removes the need to manage complicated storage rules or manual link expiration.
With uploads, processing, and access handled, your engineers are finally free to focus on what really matters.
What Your Team Actually Builds
Once the file handling is managed by Filestack, your engineers can focus on the parts that truly matter, the features that make your portal different.
The assignment lifecycle: Creating assignments, publishing them, setting deadlines, handling late submissions, attaching rubrics, this is core product logic.
User roles and permissions: Managing instructors, teaching assistants, students, and admins. Defining who can submit, grade, edit, or view content. This reflects how your institution or platform actually operates.
The gradebook: Scoring, adding feedback, annotations, grade calculations, exports, this is where real value is created for users.
Plagiarism integration: If you need to connect with services like Turnitin or similar tools, that integration lives in your backend. It can be triggered automatically after a submission is processed.
These are meaningful engineering challenges that improve your product. Debugging chunked upload failures at 2 AM is not.
Let’s see how all of this works together in a real-world submission flow.
A Real Submission Flow, End to End
Let’s make this practical.
An instructor creates a project that requires:
A code archive (ZIP)
A written report (PDF or DOC)
Supporting screenshots
Students open the submission form. They drag and drop files or import them from Google Drive. The File Picker checks file types and enforces the 500MB limit in the browser before the upload even begins.
The files are then uploaded to Filestack.
Automatically, the processing workflow runs:
Virus scan completes
DOC files convert to PDF
Images are compressed and optimised
Once processing finishes, your webhook endpoint receives a notification. Your backend updates the submission record in the database and sends the grader a secure, time-limited access link.
The grader opens the submission and sees:
Properly formatted documents
Optimised images
Secure access
Without any format confusion, security concerns or late-night infrastructure issues during exam week.
From architecture decision to full integration, this is realistically a one-day implementation for an experienced engineer.
If your team expects heavy traffic or large assets, the guide to large file uploads explains best practices for handling big files reliably. And if you’re planning for scale, managing multiple student submissions covers how to support high-volume uploads efficiently.
This article was originally published on the Filestack blog.
Top comments (0)