syketag/syketagCompliance
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
josephSummerhays17
2026-05-12 15:40:22 -06:00
parent 5b279865a1
commit 1eac72b3cd
31 changed files with 1192 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DesignDoc
+91 -34
View File
@@ -6,13 +6,15 @@ LogJensticks is a trucking application management system that automates the proc
## Architecture
### Infrastructure
- **2 Docker Containers**: Go server + MongoDB database orchestrated with Docker Compose
- **3 Docker Containers**: Caddy (reverse proxy + static frontend) + Go server + MongoDB, orchestrated with Docker Compose
- **Build System**: Makefile for building, running, and testing
- `make build` - Compiles code and builds Docker containers
- `make run` - Starts all containers
- `make run server` - Starts only the server
- `make run db` - Starts only MongoDB
- `make run test` - Runs unit tests
- `make build` - Compiles Go binary
- `make run` - Builds Docker images and starts all containers
- `make run-server` - Starts only the Go server
- `make run-db` - Starts only MongoDB
- `make run-caddy` - Starts only Caddy
- `make run-frontend` - Starts Vite dev server locally (no Docker)
- `make run-test` - Runs unit tests
---
@@ -25,9 +27,9 @@ LogJensticks is a trucking application management system that automates the proc
| POST | `/logout` | Authenticated | User logout |
| GET | `/health` | Public | Health check endpoint |
> **Unregistered Flow**: Truckers may use the system without registering. Upon first upload/submit the server issues a random `unreg_token` stored in a **secure, HTTP‑only** cookie. "Secure" means the browser will only send it over HTTPS connections, preventing exposure on unencrypted networks. "HTTP‑only" means JavaScript running in the browser cannot read the cookie; this reduces the risk of token theft via XSS. All subsequent requests (save, submit, get, status) require that cookie; the token is a single-use key that only allows access to applications created with the same token. Tokens cannot access others' applications. Registration upgrades the session to a normal authenticated user and allows reuse of prior documents.
> **Unregistered Flow**: Carriers may use the system without registering. Upon first upload/submit the server issues a random `unreg_token` stored in a **secure, HTTP‑only** cookie. "Secure" means the browser will only send it over HTTPS connections, preventing exposure on unencrypted networks. "HTTP‑only" means JavaScript running in the browser cannot read the cookie; this reduces the risk of token theft via XSS. All subsequent requests (save, submit, get, status) require that cookie; the token is a single-use key that only allows access to applications created with the same token. Tokens cannot access others' applications. Registration upgrades the session to a normal authenticated user and allows reuse of prior documents.
### Application Management (Trucker)
### Application Management (Carrier)
| Method | Endpoint | Access | Description |
|--------|----------|--------|-------------|
| POST | `/saveApplication` | Public or cookie | Save application as draft (auto-generates `app_id`). Sets/reads `anon_token` cookie when user is not registered. |
@@ -35,14 +37,22 @@ LogJensticks is a trucking application management system that automates the proc
| GET | `/getApplication/:applicationID` | Authenticated or cookie | Retrieve application details. Registered users may view their whole history; unregistered users may only view apps tied to their current `unreg_token`. |
| GET | `/applicationStatus/:applicationID` | Authenticated or cookie | Check status and results with same access rules as above. |
### Application Review (Approver/Manager)
| Method | Endpoint | Access | Approvers Only | Description |
### Application Review (Broker)
| Method | Endpoint | Access | Brokers Only | Description |
|--------|----------|--------|---|-------------|
| GET | `/approvalQueue` | Yes | - | Get list of pending applications |
| GET | `/getApplication/:id` | Yes | - | Retrieve application for review (shows all details including check results) |
| POST | `/approve/:applicationID` | Yes | - | Approve application with optional internal comments |
| POST | `/reject/:applicationID` | Yes | - | Permanently reject application with internal reason (applicant will not see reason) |
| POST | `/return/:applicationID` | Yes | - | Return application to applicant for corrections with required feedback message |
| POST | `/reject/:applicationID` | Yes | - | Permanently reject application with internal reason (carrier will not see reason) |
| POST | `/return/:applicationID` | Yes | - | Return application to carrier for corrections with required feedback message |
### Lane Management
| Method | Endpoint | Access | Description |
|--------|----------|--------|-------------|
| POST | `/lanes` | Broker | Create a new lane; returns the lane ID and shareable link |
| GET | `/lanes` | Broker | List all lanes created by the authenticated broker |
| GET | `/lanes/:laneID` | Public (via link) | View lane details |
| POST | `/lanes/:laneID/bid` | Authenticated Carrier | Place a bid on a lane; adds carrier's ID to `bidding_carriers` |
### User Management (Admin/Manager)
| Method | Endpoint | Access | Description |
@@ -63,16 +73,22 @@ LogJensticks is a trucking application management system that automates the proc
### Public Pages (HTML/CSS/Vue.js)
- `/login` - User authentication form
### Trucker Pages (Authenticated or Unregistered)
### Carrier Pages (Authenticated or Unregistered)
- `/apply` - Application submission form (multi-step form with file uploads). Works without login; unregistered users are issued a token cookie. Registered users can save and reuse documents.
- `/applicationConfirmation` - Post-submission confirmation with application ID and notice about token cookie for unregistered users.
- `/applicationStatus` - Track application progress and view check results. Unregistered users may only access apps created with current token.
- `/register` - Optional sign-up page for users who want an account to retain history and reuse files.
### Approver/Manager Pages (Authenticated + Authorized)
### Broker Pages (Authenticated + Authorized)
- `/approvalQueue` - List of pending applications for review
- `/reviewApplication/:applicationID` - Detailed application review interface with approve/reject actions
- `/dashboard` - Manager dashboard with application statistics
- `/lanes` - List of broker's lanes with bid counts
- `/lanes/create` - Form to create a new lane
- `/lanes/:laneID` - Lane detail view showing all bids
### Carrier Pages (Lane Bidding)
- `/lanes/:laneID` - Public lane view; authenticated carriers can place a bid
---
@@ -102,8 +118,8 @@ LogJensticks is a trucking application management system that automates the proc
- `app_id` (UUID) - Application ID
- `submitted_timestamp` (UTC timestamp) - When application was submitted
- `status` (string) - Current status: "draft", "submitted", "processing", "approved", "rejected", "returned", "human_review"
- `approver_notes` (string, optional) - Internal notes from approver (not visible to applicant)
- `correction_feedback` (string, optional) - Feedback message sent to applicant when application is returned
- `broker_notes` (string, optional) - Internal notes from broker (not visible to carrier)
- `correction_feedback` (string, optional) - Feedback message sent to carrier when application is returned
- `unreg_token` (string, optional) – Random token assigned to unregistered users; stored in cookie and used to authorize access to this application
#### Other Metadata
@@ -113,6 +129,35 @@ LogJensticks is a trucking application management system that automates the proc
#### Check Result Fields (added during processing)
- `[CheckName]` (string) - One field per check with value: "processing", "pass", "fail", or "human_review"
### Lane Document Fields
- `_id` (UUID) - MongoDB auto-generated document ID; used in URLs and shareable links
- `lane_id` (string, nullable) - Brokerage's own internal reference number for the lane; provided by the broker, not generated by the system. May be null until the broker assigns one, but must be filled in eventually.
- `pickup_state` (string, nullable) - Two-letter state code for pickup location (e.g. `"CA"`); may be derived from `pickup_address`
- `dropoff_state` (string, nullable) - Two-letter state code for dropoff location; may be derived from `dropoff_address`
- `pickup_address` (string, nullable) - Full pickup address
- `dropoff_address` (string, nullable) - Full dropoff address
- `bidding_carriers` (array of strings) - `_id`s of carriers who have placed a bid
- `created_by` (string) - Username of the broker who created the lane
- `created_by_id` (ObjectID) - MongoDB `_id` of the broker user document
> **Validation rule**: At least one of the following must be provided at creation time: `lane_id`, both state codes, or both addresses. A lane cannot be created with none of these.
#### Example Lane Document
```json
{
"_id": "<<mongo uuid>>",
"lane_id": "LN-2094",
"pickup_state": "CA",
"dropoff_state": "TX",
"pickup_address": "123 Warehouse Blvd, Los Angeles, CA 90001",
"dropoff_address": "456 Distribution Dr, Houston, TX 77001",
"bidding_carriers": ["<<carrier _id>>", "<<carrier _id>>"],
"created_by": "broker_jane",
"created_by_id": "<<ObjectID>>"
}
```
---
## Application Processing Pipeline
@@ -233,41 +278,41 @@ Each check adds a field to the document with status:
### Application State Visibility & Anti-Gaming Strategy
**Critical Rule**: Applicants must never know WHY their application was rejected unless an approver explicitly chooses to share that information. This prevents applicants from gaming the system through trial-and-error re-submissions.
**Critical Rule**: Carriers must never know WHY their application was rejected unless a broker explicitly chooses to share that information. This prevents carriers from gaming the system through trial-and-error re-submissions.
#### What Applicants CAN See
#### What Carriers CAN See
- **Approved**: Full approval message
- **Returned**: Only the `correction_feedback` message from the approver
- **Returned**: Only the `correction_feedback` message from the broker
- **Processing**: General status ("Your application is being reviewed")
- **Draft**: Their own unsent application
#### What Applicants CANNOT See
#### What Carriers CANNOT See
- **Rejected**: Application status shows "rejected" but NO reason provided
- Check results and names (even passed checks)
- Approver internal notes (`approver_notes` field)
- Broker internal notes (`broker_notes` field)
- Specific validation failures or OCR data
- Which checks failed or passed
#### What Approvers CAN See (Full Visibility)
#### What Brokers CAN See (Full Visibility)
- Complete application data
- All OCR results and extracted data
- All check results (passed, failed, human_review)
- Previous approver notes and decision history
- Previous broker notes and decision history
- Full validation details for debugging
#### Workflow States from Applicant Perspective
- **draft** → (applicant submits) → **submitted** → **processing** → **approved/rejected/returned**
- "returned" shows feedback for corrections; applicant can resubmit
- "rejected" shows no details; applicant cannot resubmit unless approver explicitly allows
#### Workflow States from Carrier Perspective
- **draft** → (carrier submits) → **submitted** → **processing** → **approved/rejected/returned**
- "returned" shows feedback for corrections; carrier can resubmit
- "rejected" shows no details; carrier cannot resubmit unless broker explicitly allows
- **Unregistered token behavior**: each new unregistered session creates a fresh token. A token cannot access or enumerate previous sessions; clearing cookies removes access. This helps protect sensitive documents from snooping by others using the same browser.
---
## User Roles & Access Control
### Role Types
- **Unregistered Trucker** – No login required. Receives a transient `unreg_token` cookie to upload and view only the applications tied to that token. Cannot see previous tokens’ data. Token persists until browser clears it or is upgraded by registration.
- **Registered Trucker/Applicant** – Logs in normally. Can view full submission history, reuse documents, and update profile.
- **Approver/Manager** – Can review applications, approve/reject/return, manage users
- **Unregistered Carrier** – No login required. Receives a transient `unreg_token` cookie to upload and view only the applications tied to that token. Cannot see previous tokens’ data. Token persists until browser clears it or is upgraded by registration.
- **Registered Carrier** – Logs in normally. Can view full submission history, reuse documents, and update profile.
- **Broker** – Can review applications, approve/reject/return, manage users
- **Admin** – Full system access, user management, configuration
### Authentication
@@ -321,11 +366,23 @@ Or on error:
## Database Considerations
### Recommended MongoDB Indexes
**applications collection**
- `_id` (automatic)
- `submitted_timestamp` (for sorting/filtering applications)
- `status` (for querying by application status)
- `submitted_timestamp` (for sorting/filtering)
- `status` (for querying by status)
- `driver_license_num` (for duplicate detection)
- `app_id` (if not using `_id` as primary key)
**lanes collection**
- `_id` (automatic)
- `created_by` (for listing a broker's lanes)
**users collection**
- `username` (unique)
**sessions collection**
- `token` (unique)
- `expires_at` (TTL)
### Data Retention
- Applications should be archived after [TBD] days/months
@@ -350,4 +407,4 @@ Or on error:
- Integration with external validation services (FMCSA, state registries)
- Multi-language support
- Mobile application
- Webhook integrations for downstream systems
- Webhook integrations for downstream systems