Project Status

IndiaPRIDE AutoDoc — Project Status

Single source of truth for current project state. Update whenever a milestone is completed. Last updated: 2026-09-14

1. Project Overview

AutoDoc is a document-template automation tool: members upload a .docx template containing <placeholder> or {placeholder} tags, fill in values, and generate a merged document. The core requirement driving its design is that the merged document should not change page count relative to the original template — the same guarantee the original Word/win32com script gave via Word's live pagination, now reproduced using a portable, no-root LibreOffice install on the Linux server.

Generated from the IndiaPRIDE Framework template (github.com/IndiaPRIDE-COM/framework). This repository has its own GitHub repo (IndiaPRIDE-COM/autodoc), its own database (indiapri_autodoc), and its own cPanel deployment (~/autodoc, autodoc.indiapride.com) — entirely independent of the framework it was generated from.

2. Current State Summary

Item	Value
Package name	`autodoc` (`src/autodoc/`)
Version	0.1.0
Git remote	`git@github.com:IndiaPRIDE-COM/autodoc.git`
Deployment	cPanel (Phusion Passenger via a2wsgi), `~/autodoc` on the server
Database	MySQL/MariaDB, `indiapri_autodoc`
LibreOffice	Portable install at `~/opt/libreoffice` (24.8.7.2 — chosen for compatibility with this server's older glibc 2.28; the current 26.x release requires a newer glibc this server doesn't have)

3. Architecture

Technology Stack

Python 3.11, FastAPI, SQLAlchemy 2.0, MySQL/MariaDB (PyMySQL)
python-docx — template parsing, placeholder detection, run-level merging
pypdf — counting pages in a rendered PDF
LibreOffice (headless, portable, no root) — real page counting and PDF preview/generation rendering
JWT (python-jose) + bcrypt (passlib) — authentication
markdown — renders this project's own docs at /guide

Directory Layout

src/autodoc/
├── app.py                    # ASGI entry point
├── core/
│   ├── application.py        # create_app() factory; auto-migrates DB schema on startup
│   ├── playground.py         # /playground tour + /playground/identity deployment banner
│   ├── docs_viewer.py        # /guide - renders this project's own markdown docs
│   └── project_dashboard.py  # inherited from the framework template; DISABLED (see below)
├── auth/                     # register/login/me/bootstrap + admin member management
├── documents/
│   ├── routes.py             # upload, list, values, generate, preview, settings
│   └── schemas.py
├── services/
│   └── document_processing.py  # placeholder detection, merge, page-fit shrink, PDF conversion
├── models/
│   ├── document.py            # Document (per-member, owner_id-scoped)
│   ├── app_settings.py        # AppSettings singleton (max_upload_mb)
│   └── examples/user.py       # User (roles: admin/manager/user)
├── database/config.py         # create_tables() + sync_missing_columns() auto-migration
└── static/index.html          # Login/Register/Logout + Documents + admin Members UI

Important: the project generator is disabled here

The framework template this project was generated from includes a project-generator feature (/playground/project, create-project.sh) for spawning further subdomain projects. That is intentionally disabled in AutoDoc (ENABLE_PROJECT_GENERATOR is unset/false in .env) — AutoDoc is a leaf application, not a template for spawning other projects. project_dashboard.py and services/project_generator.py are present only because they were copied in at generation time; they are dead code here and can be deleted if this project's .env is ever confirmed to never need them.

4. Completed Modules

Module	Status	Description
Auth / Members	✅ Done	Register/login/bootstrap; admin-only member CRUD, role change, activate/deactivate, with self-action guards. Members tab hidden client-side for non-admins; every admin action also enforced server-side (`require_role("admin")`), confirmed via testing that a `user`-role account gets 403 on member list/settings endpoints.
Document upload	✅ Done	`.docx`-only, size-limited (admin-configurable, default 5MB, enforced both client- and server-side), stores the file + detected placeholders + real page count (via LibreOffice) on upload.
Placeholder detection	✅ Done	Regex matches both `<name>` and `{name}` styles in paragraphs and table cells. Values are always entered as bare `fieldname` (no brackets) regardless of which style the template uses — `canonical_key()` normalizes both.
Values input	✅ Done	Two synced UI modes: paste-all-at-once (`fieldname: value` or tab-separated, auto-detected per line) and an individual-fields table (Placeholder / Value columns). Switching modes preserves whatever was typed in the other.
Check Match	✅ Done	Validates every placeholder has a value, including computed aliases (e.g. an `<allotteeaddress>` → `<allotteeresidence>` alias, and Indian-style number-to-words for a `<value>` field) matching the original template's business rules. Result message persists correctly across the table's post-check refresh.
Page-fit generation	✅ Done	`generate_with_page_fit()`: merges all values at normal size, checks the real page count once via LibreOffice, and — only if it grew — shrinks the whole page uniformly (every explicitly-sized run and every used style, not just the inserted values) in 0.2pt steps down to a fixed 8pt floor, re-checking a handful of times until it fits or bottoms out. See Document Processing for why this replaced an earlier per-placeholder approach.
Preview / Download	✅ Done	Both driven by the same merge; Preview renders to PDF via LibreOffice and opens in a new tab, Download returns the merged `.docx`. Both support a `fit=true/false` toggle (UI: "Keep original page count" vs "Just replace placeholders").
Admin settings	✅ Done	Max upload size (MB), admin-only, enforced both client- and server-side. (A minimum-font-size admin setting was built, then removed per explicit request — the 8pt floor is now a fixed internal constant, not user-configurable.)
DB auto-migration	✅ Done	`sync_missing_columns()` runs on every startup, adding any nullable column a model declares but an existing table is missing. Does not handle NOT NULL columns (documented limitation) — those still need a manual `DROP TABLE`/backfill once, which has happened twice this session as the schema evolved.
LibreOffice integration	✅ Done	Portable install, no root, isolated to this account (`~/opt/libreoffice`, 696MB). Used for: page counting on upload, PDF preview rendering, and page-fit generation's page-count checks.
Documentation	✅ Done	Product README, technical architecture/deployment documentation, complete feature list, one-page brochure, multi-page feature booklet, and member/admin working manual are maintained in the repository.

5. Known Issues / Limitations

Run-splitting edge case: placeholder replacement (_replace_placeholder_in_place) only isolates an occurrence into its own run if the whole placeholder text sits inside a single existing run. An occurrence split across multiple runs (rare — usually only from a formatting change mid-placeholder in the original document) falls back to a whole-paragraph substitution, which loses per-run formatting in that one paragraph. Verified working correctly for the real conveyance-deed template.
Page-fit is a uniform batch shrink, not per-placeholder: an earlier version checked the page count after every single placeholder (matching the original Word script exactly), but this reliably exceeded the server's request timeout with realistic placeholder counts (16+), since each check launches a LibreOffice process. The current approach merges everything first and shrinks the whole page together if needed — less surgical (a field that individually wouldn't have overflowed may still shrink slightly), but finishes in seconds instead of minutes.
LibreOffice version is pinned to 24.8.7.2, an older release chosen for glibc compatibility with this specific server. It does not receive security patches. Acceptable given it only processes documents this application's own authenticated members upload, but worth revisiting if this project ever moves to a host with a newer glibc (or root access to install a current version).
DB auto-migration doesn't handle NOT NULL columns — see Completed Modules above.
The app_settings table has an orphaned min_font_size_pt column left over from the removed admin setting (the model no longer references it; harmless, but worth a cleanup migration if the schema is ever formally tidied).
No tests — everything has been verified via TestClient scripts during development (documented in commit history/session transcript), not a checked-in test suite. Worth adding before this project takes on more contributors.

6. Next Steps (not yet started)

Continue the step-by-step UI pass on the remaining Documents screens, especially the document editor pane and table-heavy views on mobile.
Add focused smoke tests for the key server-rendered flows so each section can be checked in isolation without broad JS refactors.
Consider LibreOffice's headless conversion being spawned per-request — under real concurrent load, multiple simultaneous Preview/Generate calls will each launch their own soffice process; worth monitoring server resource usage in production and potentially serializing/queueing if it becomes a bottleneck.
The auto-reduce-footer-margin idea (use leftover blank space instead of only shrinking font) was discussed and deliberately deferred — not implemented, flagged as a future enhancement if font-shrinking alone proves insufficient for some templates.
Clean up the dead project_dashboard.py/project_generator.py files inherited from the template, once confirmed they're truly unused here.

7. Important Architectural Decisions

Decision	Rationale
Support both `<placeholder>` and `{placeholder}` syntax	`<>` collided with HTML rendering (a real bug we hit and fixed via escaping); `{}` is the safer long-term convention, but the existing real template already uses `<>`, so both are detected simultaneously rather than forcing a migration.
Values entered as bare `fieldname`, no brackets	Decouples the human data-entry format entirely from whichever bracket style a given template happens to use.
Auto-detect tab vs colon per line	Matches the real workflow: colon for hand-typing, tab for pasting two columns straight out of Excel. Plain CSV was ruled out — the real data (addresses, Indian-formatted amounts) is comma-heavy, making comma-delimited parsing unreliable without careful quoting most users won't do correctly.
Whole-page uniform shrink, not per-value shrink	Shrinking only the inserted values looked visually inconsistent (some fields shrunk much more than others) and didn't help when the overflow came from a value wrapping onto an extra line by itself. Shrinking every sized run/style together, uniformly, looks consistent and directly addresses page overflow regardless of its source.
Batch page-check instead of per-placeholder	Per-placeholder checking (matching the original script exactly) was tried first and reliably timed out with realistic placeholder counts. Switched to a single post-merge check plus a handful of shrink iterations.
Portable, no-root LibreOffice install	This is shared cPanel hosting with no root access — a normal package-manager install isn't possible. LibreOffice's official tarballs can be extracted into the account's own home directory and never touch anything system-wide.
Min font size hardcoded, not admin-configurable	Explicitly requested removal after review — the floor still needs to exist internally to prevent absurd shrinking, it just doesn't need a knob.
Everything server-side, nothing local	Explicit requirement for a commercial multi-tenant product — no step should require a member's own PC (ruled out an earlier "download a package to run a script locally" design).

8. Development Rules

Same as the framework template this project was generated from: 1. Verify changes compile/import before considering a task done. 2. Keep commits meaningful — one logical change per commit. 3. The user runs git commit/git push/SSH commands themselves — prepare exact commands rather than executing git write operations directly. 4. This is a Windows dev machine (c:\home\indiapri\autodoc) syncing to a Linux cPanel server via GitHub — don't assume Unix tools locally or Windows conventions on the server.

This file is the single source of truth for project state. Any AI assistant picking up this project should read this file first.