Dear Monks,

at my job i am last one who understands and worships spiritual Perl power.
Because of that i was sent to dungeon full of hash pounds and dollar signs, named Connetor.pl, to alter it's way of working.

I was given 14k lines of wise, full of vaild and even preety, but not self-documenting Perl code. sub definitions are mixed with "main" code and sub calls, database routine is ending just to call curl on the main "thread" and after which there's another sub defined.
Obviously it's not helping to understand what, or how, this code is relly doing, so i decided to split it into functional packages

So, as i did not found any more elegant way to include "reusable" code, i decided to group subs accessing database into Database.pm, these interacting with API for data input ended in API.pm and so on, leaving main to just call predeclared subs and decide either to INSERT them into databse or print.

Main package had been shrinked into circa 300 lines and i've gained much visibility. When i wanted to proceed to unit tests and documenting every sub functionality (like: this function CONSUMES scalar with URL, PRODUCES array with "img scr" tags) i found that my packaging solution might not be wisest thing done there.
Of course i didn't foreseen that namespaces can be an issue here, and they were

main calls custom wrapper to eventually create instance of DBI object and holds its ref in $main::sql.
sub sql_connect embedded into Database.pm (Databae::sql_connect to be precise) tries to call "connect" method on $sql, but API.pm's methods albo uses some $sql methods
and there's alot of shared variables like this.
Before my modularization attempt everything worked, now i am forced to replace all "my"s into "our"s definitions in main in order to grant access to these variables by modules.

also changing all $variable in modules to $main::variable syntax and constanlty growing out @EXPORT = qw (...); gave me that strage feeling like trying to leave dungeon leads me to catacombs.

what am i missing here? How do properly split this code into logical chunks of separate files, but keeping namespace "main"?

ANY ideas will be appreciated.
my main goal is to document code, understand it's flow and based on that create another functionality