FreightFolio (Logistics SaaS)

Modular logistics SaaS backend for small carriers - AR/AP modules with per-service migrations, AWS Cognito authentication, and Dockerized PostgreSQL.

LogisticsSaaS PlatformAuth (AWS Cognito)API Backend

Overview

Private, in-development SaaS backend designed for small freight carriers. It provides a modular system to streamline logistics operations through FastAPI services, focusing on load management, invoicing, and secure user authentication via AWS Cognito. Multi-tenant data isolation is designed and planned for an upcoming milestone. Not yet deployed; the source is private, with a public overview repo.

Tech Stack

View more →
Python
Languages
FastAPI
Backend
SQL
Languages
PostgreSQL
Data Engineering
SQLAlchemy
Data Engineering
Docker
DevOps & Tools
Git
DevOps & Tools
GitHub Actions
DevOps & Tools
AWS
DevOps & Tools

Challenges & Solutions

Designing for tenant data isolation

Planned multi-tenancy requires strict data isolation on a shared PostgreSQL schema with tenant_id on every table, without hurting query performance on tenant-scoped APIs.

Solution: Designed tenant-aware query filters at the FastAPI dependency layer with request-scoped tenant context, and composite indexes on (tenant_id, key columns). Documented patterns for inserts and joins so tenancy can be enabled consistently across services.

Impact: The isolation model is settled and documented, ready to enable when multi-tenancy lands on the roadmap.

postgresqlsqlfastapisqlalchemy + alembicapi-designperformance

Integrating AWS Cognito with tenant-aware RBAC

Needed authentication/authorization with roles and tenant context; JWTs had to carry role + tenant_id and be verified per route.

Solution: Provisioned Cognito user pool & app client; normalized users/roles/tenants in Postgres; added JWT verification middleware and route-level role checks; mapped claims → request context for downstream queries.

Impact: Secure authentication in place: route-level guards, least-privilege access, and auditable user/role changes.

awsfastapipostgresqlapi-securityauth

Untangling migration conflicts across services

Shared migrations caused version collisions and broken upgrades when services evolved independently.

Solution: Split into per-service Alembic trees with service-specific version tables; enforced naming/versioning conventions; added CI checks to run forward/backward migrations per service before merge.

Impact: Zero migration conflicts since split; reproducible up/down across services and safer deploys.

sqlalchemy + alembicpostgresqlgithub actionsci/cd

Consistent local env across Windows and macOS

Onboarding and troubleshooting differed by OS (paths, shells, env vars, Docker behavior).

Solution: Created OS-aware setup scripts (Windows/mac), `.env` templates, Make/NPM tasks, and Docker Compose profiles; documented one-command boot and added preflight checks.

Impact: Reduced setup time to minutes with identical local parity; fewer ‘works on my machine’ issues.

dockergitgithub actionsdevx

Links

GitHubCase Study