my-enterprise-app/

├── README.md # Project overview, setup instructions, API

docs link
├── requirements.txt # All production dependencies (FastAPI,
SQLAlchemy, Pydantic, etc.)
├── requirements-dev.txt # Development dependencies (pytest, black,
mypy, etc.)
├── pyproject.toml # For packaging, linting configs (if using
poetry or similar)
├── .env.example # Template for environment variables
(DB_URL, SECRET_KEY, etc.)
├── .env # Local env vars (gitignored)
├── .gitignore # Standard Python ignores + .env, logs, etc.
├── .pre-commit-config.yaml # Pre-commit hooks for linting, formatting
├── pytest.ini # Pytest configuration
├── alembic.ini # Alembic config for DB migrations
├── alembic/ # Database migrations
│ ├── env.py # Alembic environment script
│ ├── script.py.mako # Migration template
│ └── versions/ # Auto-generated migration files
│ └── xxxx_initial_migration.py
├── logs/ # Log files (gitignored)
│ └── app.log
├── static/ # Static files (images, CSS/JS if needed for
any web views)
│ ├── uploads/ # User-uploaded files
│ └── media/ # Generated media
├── tests/ # Comprehensive test suite
│ ├── __init__.py
│ ├── conftest.py # Pytest fixtures (test DB, mock services)
│ ├── unit/ # Unit tests
│ │ ├── test_models.py
│ │ ├── test_schemas.py
│ │ └── test_utils.py
│ ├── integration/ # Integration tests
│ │ ├── test_api_endpoints.py
│ │ └── test_db_operations.py
│ └── e2e/ # End-to-end tests (using httpx or similar)
│ └── test_user_flow.py
├── app/ # Main application package
│ ├── __init__.py
│ ├── main.py # FastAPI app instantiation, middleware,
lifespan events
│ ├── core/ # Core shared utilities and configs
│ │ ├── __init__.py
│ │ ├── config.py # Settings management (pydantic-settings or
environs)
│ │ ├── security.py # Auth helpers (JWT encode/decode, password
hashing)
│ │ ├── events.py # Startup/shutdown events (e.g., connect to
DB, Redis)
│ │ ├── logging.py # Centralized logging config (structlog or
logging)
│ │ ├── middleware.py # Custom middleware (CORS, rate limiting,
auth)
│ │ └── exceptions.py # Custom exceptions and HTTPException
handlers
│ ├── db/ # Database layer
│ │ ├── __init__.py
│ │ ├── base.py # Base class for SQLAlchemy models
│ │ ├── session.py # DB session management (async/sync)
│ │ └── engine.py # DB engine creation
│ ├── models/ # SQLAlchemy ORM models (shared or per-
module)
│ │ ├── __init__.py
│ │ ├── user.py # Example: User model
│ │ └── base.py # Declarative base
│ ├── schemas/ # Pydantic schemas for API (input/output)
│ │ ├── __init__.py
│ │ ├── user.py # UserCreate, UserResponse schemas
│ │ └── extended.py # Extended schemas for internal use
│ ├── crud/ # CRUD operations (repository pattern)
│ │ ├── __init__.py
│ │ ├── base.py # Base CRUD class
│ │ └── user.py # User CRUD functions
│ ├── services/ # Business logic services (injectable)
│ │ ├── __init__.py
│ │ ├── auth.py # Authentication service (login, token
refresh)
│ │ ├── email.py # Email service (using aiosmtplib or
similar)
│ │ └── notification.py # Notification service (integrates with
queues)
│ ├── api/ # API routers and dependencies
│ │ ├── __init__.py
│ │ ├── deps.py # Dependency injections (current_user,
get_db)
│ │ └── v1/ # API version 1 (modular by feature)
│ │ ├── __init__.py
│ │ ├── api.py # Main router including sub-routers
│ │ └── endpoints/ # Feature-specific routers
│ │ ├── __init__.py
│ │ ├── users.py # User endpoints (CRUD, auth)
│ │ ├── orders.py # Orders module (for ERP-like)
│ │ ├── invoices.py # Invoicing (Zoho-like)
│ │ ├── teams.py # Teams/collaboration (MS Teams-like)
│ │ └── order_pick.py # Order Pick endpoints (warehouse workflows,
approvals)
│ ├── modules/ # Modular features/apps (scalable for
enterprise)
│ │ ├── __init__.py
│ │ ├── users/ # Users module (self-contained)
│ │ │ ├── __init__.py
│ │ │ ├── models.py # Module-specific models
│ │ │ ├── schemas.py # Module-specific schemas
│ │ │ ├── crud.py # Module CRUD
│ │ │ ├── services.py # Module business logic
│ │ │ ├── api.py # Module router
│ │ │ └── tasks.py # Background tasks (e.g., user verification)
│ │ ├── orders/ # Orders module
│ │ │ ├── __init__.py
│ │ │ ├── models.py
│ │ │ ├── schemas.py
│ │ │ ├── crud.py
│ │ │ ├── services.py # E.g., order processing, inventory sync
│ │ │ ├── api.py
│ │ │ └── tasks.py # E.g., order fulfillment queue
│ │ ├── invoices/ # Invoices module
│ │ │ ├── __init__.py
│ │ │ ├── models.py
│ │ │ ├── schemas.py
│ │ │ ├── crud.py
│ │ │ ├── services.py # E.g., PDF generation, payment integration
│ │ │ ├── api.py
│ │ │ └── tasks.py # E.g., recurring invoice scheduler
│ │ ├── teams/ # Teams module
│ │ │ ├── __init__.py
│ │ │ ├── models.py # E.g., Team, Channel models
│ │ │ ├── schemas.py
│ │ │ ├── crud.py
│ │ │ ├── services.py # E.g., real-time messaging (integrate
WebSockets)
│ │ │ ├── api.py
│ │ │ └── tasks.py # E.g., message archiving
│ │ ├── twinfield/ # Twinfield sync module (for ERPNext ↔
Twinfield invoice sync)
│ │ │ ├── __init__.py
│ │ │ ├── models.py # E.g., SyncJob, SyncLog, TwinfieldConfig
models
│ │ │ ├── schemas.py # E.g., SyncRequest, SyncStatusResponse
schemas
│ │ │ ├── crud.py # CRUD for sync jobs, configs, logs
│ │ │ ├── services.py # Business logic: ERPNext API calls,
Twinfield API integration, sync orchestration
│ │ │ ├── api.py # Endpoints: trigger sync, view sync
history/status
│ │ │ └── tasks.py # Background tasks: periodic syncs (Celery),
error retry queues
│ │ └── order_pick/ # Order Pick module (warehouse picking
workflows with ERPNext integration)
│ │ ├── __init__.py
│ │ ├── models.py # E.g., Picklist, PickItem, Approval,
Assignment models
│ │ ├── schemas.py # E.g., PicklistCreate, MergeRequest,
ApprovalResponse schemas
│ │ ├── crud.py # CRUD for picklists, assignments, approvals
│ │ ├── services.py # Business logic: ERPNext order
fetch/submit, workflow orchestration, role-based access
│ │ ├── api.py # Endpoints: fetch orders, merge/assign,
pick progress, review/approve
│ │ └── tasks.py # Background tasks: periodic ERPNext syncs,
notifications, reconciliation
│ ├── utils/ # Shared utilities
│ │ ├── __init__.py
│ │ ├── validators.py # Custom Pydantic validators
│ │ ├── pagination.py # Pagination helpers
│ │ ├── file_handler.py # File upload/download utils
│ │ └── cache.py # Caching (Redis integration)
│ └── background/ # Background task management
│ ├── __init__.py
│ ├── tasks.py # Celery tasks or FastAPI BackgroundTasks
│ └── worker.py # If using Celery, the worker script
└── docs/ # Documentation
├── api/ # Auto-generated OpenAPI docs (or manual)
│ └── index.html # Served via /docs in FastAPI
├── architecture.md # High-level architecture diagram (text-
based)
 └── deployment.md # Production deployment guide (no Docker,
use systemd/Gunicorn)

-------------------------------------

Order Pick Application –Technical Document

ERPNext Integration • FastAPI Backend • React/Vue Frontend

Lead Developer: Rohit | Developer: Saurav

October 18, 2025

1. Introduction

1.1 Purpose

This document is the comprehensive technical and functional specification for the
Order Pick Application. The application integrates with ERPNext but runs most
warehouse and portal workflows within this app for performance, control, and
reliability.

1.2 Goals

Deliver a responsive, offline-friendly UI for warehouse picking and controller

review.

Ensure reliable, auditable synchronization with ERPNext for orders,

Secure the platform with OAuth 2.0 and role-based access control (RBAC).

Use background jobs for ERP syncs, reports, and heavy tasks; apply caching for low-
latency reads.

Establish observability (logging, metrics, tracing) and a predictable CI/CD

pipeline.

2. Workflow Summary

1. Application fetches Sales Orders from ERPNext.

2. Warehouse Manager views all orders as picklists.

3. Manager can merge multiple orders into one picklist (optional).

4. Manager assigns the picklist to a Picker.

5. Picker starts picking based on stock (check the workflow) and saves progress.
6. Saved picklist goes back to Manager for review.

7. Manager can approve or reject the picklist:

• If Rejected → returns to Picker with rejection reason.

• If Approved → moves to Backoffice for final approval.

8. Backoffice User reviews and gives final approval.

9. After final approval, picklist is submitted to ERPNext and related Sales Orders
are updated.

3. Roles and Responsibilities

Warehouse Manager: Views, merges, assigns, and reviews picklists.

Picker: Picks items, updates quantities, and resubmits after rejections.

Backoffice User: Gives final approval and submits to ERPNext.

System: Handles synchronization with ERPNext.

4. System Components

Frontend: React or Vue.js web interface.

Backend: FastAPI (Python) for API and workflow logic.

Database: Postgress for data persistence.

Cache/Queue: Redis for caching and background jobs.

Background Jobs: Celery for ERPNext syncs and submissions.

Authentication: OAuth2 with role-based access control.

ERP System: ERPNext REST API integration.

5. Key Features

Merge multiple orders into one picklist.

Role-based dashboards for Manager, Picker, and Backoffice.

Simple three-level approval process.

Background sync with ERPNext for reliability.

Auto-refresh and error handling for failed syncs.

6. Test Scenarios

Test ID

Scenario

Expected Result
T1

Manager fetches orders

Orders list visible

T2

Merge multiple orders

Single picklist created

T3

Assign picklist

Picker receives assignment

T4

Picker saves progress

Picklist status = Saved

T5

Manager rejects

Picker sees rejection reason

T6

Manager approves

Picklist moves to Backoffice

T7

Backoffice final-approves

Picklist submitted to ERPNext

T8

ERPNext updates Sales Order

Order marked as updated

7. Developer Responsibilities

Lead Developer: Rohit

• Oversees full system design and architecture.

• Develops backend (FastAPI) and frontend (React/Vue).

• Integrates ERPNext APIs and ensures stable sync jobs.

Developer: Saurav
• Supports backend tasks, data models, and testing.

• Assists in ERPNext integration and background jobs.

8. Simplified Requirements

Basic authentication with roles (Manager, Picker, Backoffice).

Clean dashboard with picklist and order views.

Background tasks for syncing with ERPNext.

Simple approval workflow and notifications.

Lightweight logs and error tracking.

9. Technical Architecture

9.1 Logical Architecture

Core flow: ERPNext ⇄ FastAPI (REST/WebSockets) ⇄ MariaDB/Redis ⇄ Celery

Workers(optional) ⇄ Frontend SPA. Background jobs handle push/pull with ERPNext;
cache accelerates reads

9.2 Component Responsibilities

FastAPI: auth, API endpoints, validation, orchestration, WebSockets.

Celery: ERP sync, token refresh, reconciliation, report generation, notifications.

Redis: cache, broker, distributed locks, counters.

Postgress: transactional data, queue-backed audit tables, idempotency keys.

Frontend: SPA with offline-first UX for picking workflows.

10. Risks & Mitigations

ERPNext downtime → continue with cached reads and queue writes; reconcile later.

Token misconfiguration → proactive health checks; alert on refresh failures.

Race conditions on stock → DB transactions + distributed locks + optimistic checks.

Duplicate deliveries → idempotency keys and version guards on push.

11. Workflow

12. Timeline / Deadline

Project Duration: October 18, 2025 – October 25, 2025

Final Delivery Date: October 25, 2025 (Saturday)