Empower your delivery management with my cutting-edge tool designed for rapid creation and seamless exchange of deliveries. Learn and apply best practices of Feature Sliced Design along the way..
Welcome to the Fasty App, a robust PWA designed to streamline delivery operations for couriers. Built with cutting-edge technologies like React, TypeScript, and Feature Sliced Design, our app is tailored to meet the dynamic needs of modern courier services.
- Day/Night Theme: Seamlessly switch between day and night modes for optimal readability and user experience.
- Multilingual Support: Effortlessly switch between Russian and English languages.
- Offline Capable: Enjoy uninterrupted service with PWA capabilities, ensuring your deliveries are managed even without an active internet connection.
- Multi-Platform: Access the app from mobile, tablet, or PC, ensuring a consistent experience across all devices.
- Courier Authentication: Secure login for couriers to manage their deliveries.
- Delivery Selection: Choose suitable deliveries from a list of upcoming tasks.
- My Deliveries: View your current and scheduled deliveries easily.
- History: Browse through completed deliveries for reference and record-keeping.
- Search Function: Quickly find specific deliveries using the in-app search.
- Delivery Maps: Utilize OpenStreetMap integration for precise navigation on the delivery page.
- Profile Management: Edit your profile information and change your avatar quickly and intuitively.
- Rapid Deployment: Quickly set up a comprehensive delivery service.
- Feature Sliced Design Best Practices: Showcase the best practices in Feature Sliced Design for scalable and maintainable architecture.
- Easy Onboarding: Facilitate rapid learning of the architecture for new developers.
- Collaboration-Friendly: Enable users to suggest and contribute new functionalities.
Experience the future of delivery management with the Fasty App โ where efficiency meets innovation.
Use issue and follow the rules :)
The data from repository is provided an 'As is', without any guarantees. All the data provided is used at your own risk. If you want report a bug - use issue
- General
- Quick start
- Architecture
- Authentication
- Profile Management
- Delivery Management
- Roadmap
- Why Should You Learn This?
- Contributing
- Buy Me A Coffee
- License and Changelog
- NodeJS: 20 (My version at building time)
- PNPM
- Yarn: 1.22 (only if you doesnt have backend)
If you have your own backend:
- Clone this repository:
- Go to
fasty-package-delivery-courier-pwafolder. - Make
.envfrom.env.exampleand past your data - Install pnpm via
npm install -g pnpm - Install depends via
pnpm i - Build project ->
pnpm build& Enjoy !
If you need backend with demoData:
- Register Atlas account and create mongodb database
- clone Fasty.API
- Go to
fasty-pwa-demo-api - Make
.envfrom.env.exampleand past your settings - Install yarn via
npm install -g yarn - Install deps
yarn install; - Seed demo data via
prisma db seed. - Start your backend
yarn dev(start in dev mode) - Return to upper guide & Enjoy it!
Developer mode
- Run
pnpm dev
Preview (do not use for production)
pnpm preview
Production with nginx
- install
nginxon your server - copy
distto/usr/share/nginx/html - create nginx config file based on template
user nginx;
worker_processes auto;
events { worker_connections 1024; }
http {
server {
server_tokens off;
listen 8080;
root /usr/share/nginx/html;
include /etc/nginx/mime.types;
location / {
try_files $uri $uri/ /index.html;
}
gzip on;
gzip_vary on;
gzip_http_version 1.0;
gzip_comp_level 5;
gzip_types
application/atom+xml
application/javascript
application/json
application/rss+xml
application/vnd.ms-fontobject
application/x-font-ttf
application/x-web-app-manifest+json
application/xhtml+xml
application/xml
font/opentype
image/svg+xml
image/x-icon
text/css
text/plain
text/x-component;
gzip_proxied no-cache no-store private expired auth;
gzip_min_length 256;
gunzip on;
}
}
The offline mode is enabled through the following mechanisms:
- Data Provider: Workbox by Google for PWA capabilities.
- Connection Status Tracking: Monitoring the internet connection status.
Caching settings for requests can be found in vite.config.mts, allowing you to customize how data is cached and retrieved when offline.
The mechanism for determining if the user is online can be found in @/entities/viewer, ensuring a seamless user experience even when the internet connection is interrupted.
Our project supports multiple languages, ensuring a localized experience for users worldwide. Below are the details of our multilingual implementation:
We use i18next as our primary library to handle multilingual capabilities. This allows us to dynamically switch languages and handle translations efficiently.
- Translation Namespaces (
translationNSs):
- We organize our translations into multiple namespaces, making it easier to manage and scale our localization files.
- Locale Folders:
- Translations are segregated into JSON files based on their context (e.g.,
entities/**/*/locale,features/**/*/locale,widgets/**/*/locale, etc.). - This ensures that translations are neatly organized and modular.
Feature Sliced Design is an outstanding architecture that has significantly contributed to the successful implementation of this project and numerous others within our company. To show our appreciation to its creators, we have decided to make a branch of this project publicly available. This allows those who are new to Feature Sliced Design to see practical implementations of various use cases. One of the versions of this application is actively used in production environments, showcasing its real-world applicability.
- shared - Core functions devoid of business logic
- api - API client for server communication, built using
Zodios - constants - Crucial global settings and configurations
- lib - Collection of global helpers and type guards
- types - Global type declarations used throughout the project
- ui - Common UI components used across the application
- assets - Additional resources required by the compiled application
- api - API client for server communication, built using
- entities - Storage and management for global business abstractions, including templates, effects, and data fetching mechanisms
- features - Logic that processes user actions with significant business value
- widgets - Components that integrate layers above without managing the data themselves
- pages - Layer where primary data handling logic resides; responsible for changing widget states or re-fetching data from the server. Note: It's considered best practice to avoid placing this logic in
widgets. - app - Entry point and initialization hub of the entire application
The main template for components is built using the following structure:
index.ts- The main entry point of the component and the point of interaction with it. We do not support other interactions to adhere to the core principles ofFeature Sliced Design.init.ts- The main file where all necessary resources for the abstraction are connected, such as localizations, and so on./locales- Storage for localization files for the current abstraction. Tip: You can copy/paste a file here to quickly add localization in your language./config- The main storage for configuration variables used in the current abstraction./lib- Helpers, type guards, and other utility functions that may be used in this abstraction and higher layers./model- The main folder or file containing the business logic of the current abstraction (models, factories, effects)./ui- All UI components related to this abstraction./@x- Allowed cross imports between entities. Note: Use with great caution to avoid circular dependencies. The decision for this convention was made by the community and is not an officialFeature Sliced Designspecification.
$$storeName: Used for naming derived stores that are based on a parent store.whatEverChanged,whatEverInited: Naming pattern for events in the main abstraction model. These events are triggered by user actions in the UI and are used to initiate core business logic processes.
The application uses a contract system for validating data received from the server. This ensures type safety and data integrity throughout the system.
Contracts help maintain a consistent data structure and prevent errors by validating incoming data against predefined schemas. This is particularly useful for:
- Ensuring data integrity
- Simplifying debugging
- Enforcing API contracts between frontend and backend
We use Zod as our primary library for data validation. Zod is a TypeScript-first schema declaration and validation library that enables comprehensive and efficient data validation.
Our application employs JSON Web Tokens (JWT) as the core mechanism for authentication and authorization. This choice facilitates a flexible system for managing user sessions and renewing tokens, ensuring a high level of security for end users.
- Flexibility: JWT allows for a dynamic and adaptable authorization process.
- Security: JWT ensures secure data transmission between the client and server.
- Offline Capability: Given that the application can function offline, the JWT facilitates a deferred verification mechanism for user tokens. This means that even if the network is disconnected, the user's session can remain valid and be verified once the connection is restored.
- Upon login, a JWT is issued and stored on the client side.
- This token is sent with each request to verify the user's identity and permissions.
- Tokens are periodically renewed to maintain security and session continuity.
- In offline mode, tokens are queued for later verification once the connection is re-established.
This approach optimizes both the user experience and the overall security architecture of the application.
Each user in the application has a personal profile stored on the server. The profile includes:
- Name: The user's full name.
- Avatar: The user's profile picture.
- Password: The user's account password.
- Delivery Search History: Records of the user's previous delivery search queries on the server.
- Additional Settings:
- Language preferences
- Theme (e.g., light or dark mode)
- Other related data
Users have the ability to:
- Update Avatar: Change their profile picture.
- Change Password: Update their account password for security.
These features provide users with the flexibility to personalize their profiles and maintain account security.
The core workflow for a courier involves the following pipeline:
- Select and take a suitable delivery order
- Maintain the delivery status
- Upon completion, set the status to indicate successful delivery
This pipeline is implemented in the application as follows:
- Delivery Marketplace: The main page features a marketplace with deliveries that have the status
createdand are not assigned to any courier. These deliveries can be filtered by date, delivery type (on foot or by car), and weight. - Assign to Delivery: Once a courier clicks
assign to delivery, the delivery status changes todeliveringand the courier is linked to the delivery. The delivery then becomes unavailable to other couriers. - Managing Delivery Status: When a delivery has the status
deliveringand is assigned to a courier, the courier can set the status todonewith an optional note for the responsible manager, or set the status tocancelledwith a mandatory reason for cancellation. - Delivery History: All deliveries of the current user with the statuses
doneandcancelledare recorded in the delivery history.
- Offline Availability: All deliveries of the current user with the status
deliveringare available offline in case of internet connectivity loss. - Delivery Map: A map is available with markers for the delivery points.
The application is currently in its beta release phase and is awaiting feedback to determine the necessity and direction of the roadmap.
Like any other project, ours is not perfect. It may have bugs and shortcomings. You have the opportunity to explore various use cases for implementing features using Feature-Sliced Design. Additionally, you are welcome to propose your improvements to our project.
Moreover, you can fork this project and build something of your own that could bring you joy or even profit, as the project is under an open license.
I am <3 contributions big or small. If you help my project --> ๐ฐlink to your profile will be here๐ฐ.
Currently I'm seeking for new sponsors to help maintain this project! โค๏ธ
With every donation you make - you're helping with development of this project. You will be also featured in project's README.md, so everyone will see your contribution and visit your contentโญ.
Copyright (c) 2023, KoninMikhail. This project under MIT license. See the changes in the CHANGELOG.md file.