Cloud, database and module setup

In this chapter - Two kinds of cloud account: root administrator vs tenant - Preparing a source-CRM database for TechieCRM's native modules - Local MongoDB mirror - Configuration values - Feature gating and add-ons

Root administrator vs tenant

The cloud Parent (techiecrm.com) has a stand-alone root/parent database that manages client registrations, users and licenses — the site root administrator's account lives there and is not a tenant. Each client company is a tenant with its own cloud database; a desktop is linked to a tenant by activating that tenant's license key. Test with a dedicated test tenant, never the root administrator account.

Requesting a workspace (www.techiecrm.com → Get Started)

A prospect fills in Request an invite: company name and the CRM(s) they use now or have tried (tick all that apply — chosen from a list of common CRMs, plus an "Other" box); their name and phone, then Country (Canada preselected), street/suite/city, Province / State (the list only shows the chosen country's regions) and Postal / ZIP code (Canadian A1A 1A1 and US 12345[-6789] formats are enforced and auto-formatted; the form also sanity-checks that the postal/ZIP code matches the province/state and city and shows a friendly warning with a "My address is correct — submit anyway" tick if it doesn't); email; deployment, data option and plan; and they must accept the Terms & Privacy Policy. The About → Contact us form asks for first name, last name, company (optional), email, subject and message (no phone/hours are published). Each submission (1) is recorded as a lead in the TechieCRM internal workspace — a Company record (matched by name, source "Website contact form", category "Lead") with a Contact under it (matched by email) — or a single Individual record when no company is given — and a Note "Contact request: " with the message; (2) emails admin@ with the details, a Reply-To to the sender and a link to the CRM record; (3) sends the sender an acknowledgement, which is also filed on their record as a sent email (Email module, category "auto-ack"). Phone is mandatory on the form. Repeat requests are detected: if the same person writes again and nobody here has logged a reply (a real email on the record, a phone/meeting/ email note, or an outbound SMS/email in Communications) since their first request, the note is filed as "ESCALATED — Contact request…", the admin email subject is prefixed ESCALATED, and the sender is told we see their first request date/time, have no record of getting back to them, and are escalating; if we DID reach out, they're told when/how and that we'll try again by phone. Nothing is created until a TechieCRM administrator opens Admin Portal → Registrations and clicks Provision & Invite (the invitation email carries the set-password link; Invite link shows it if the email doesn't arrive).

Two administration menus (cloud CRM)

• Workspace Admin — what a customer's own administrators (and TechieCRM staff while inside a workspace) manage for THEIR workspace/child database: Users, Security Groups, Teams, Preferences, UDF
• UDF Setup (Workspace Admin → UDF Setup) shows nine entity tabs (Company, Individual, Contact, Sales, Service, Marketing, Users, Projects, Inventory) with field types Text, Number, Date, Dropdown, Yes/No, Multi-line Text, Formula and Folder. Preview: this page is not yet connected to the live field definitions your records use — fields defined here don't appear on records yet. Manage user-defined fields on the desktop (Set Up UDF) for now. Setup, Email Identity, Email Templates, SMS Number, Plan & Billing. Everything here is scoped to that workspace — one customer never sees another's. Preferences is tabbed, one tab per area, and each module's ⚙ Settings button opens its own tab directly (Service opens Service; To-Do opens Calendar; Marketing opens the email-marketing connectors). Modules with no settings of their own open the Preferences page itself. The ⚙ appears only for workspace administrators, because that is who the page admits.
• TechieCRM Admin — the operator console for TechieCRM site administrators only (never shown to customers): Registrations, Tenants, All Users, Cloud Licenses, App Releases, SMS Numbers, Abuse Protection, Billing (invoices, cost breakdown), Messenger Admin, Database, Audit Log.

Abuse protection (TechieCRM Admin → Abuse Protection)

Public surfaces are rate-limited: registration max 2 per IP per 24 h (a 3rd is refused and the IP is held for review — a second company from one network usually means the client is stuck, or abuse); sign-in 5 failed attempts per account in 15 min locks the account for review (20 per IP blocks the IP); Contact us max 5 per email per 24 h (the 6th gets a dialog: "we have your messages, we'll call you"); more than 10 registration+contact submissions from one IP in an hour blocks that IP; more than 30 across ALL IPs in 10 minutes pauses registration and the contact form (fields greyed out, banner) as a possible DoS. Every incident raises a technical case in the internal workspace's Service module (client "TechieCRM Website", origin "Abuse protection"). The Abuse Protection page shows the kill switches (Pause/Resume per surface), active blocks/locks with Release, a manual "Block an IP", the last 100 events and the thresholds (env ABUSE_*).

Preparing a source-CRM database (native modules)

TechieCRM's own modules keep their data in TCRM_ tables inside the client's source SQL database during alpha/beta (they move to MongoDB at go-live).

You do not run these by hand. The first time you sign in to a database, TechieCRM checks which of its support tables are missing and creates them for you, then tells you what it set up. If your Login ID cannot create tables it says so and asks you to sign in with the source CRM's MASTER ID (or an ID granted SQL admin / db_owner on that database) — that is the only action needed, and only once per database. The scripts are idempotent, so nothing happens on later sign-ins.

Where a module lists two scripts, the second one extends the first and always runs after it. No source-CRM tables are created, altered or written to by any of the above.

The workspace ID — how TechieCRM recognises a database again

The first time you sign in to a source-CRM database, TechieCRM writes one row into TCRM_Workspace: a permanent identifier for that set of records. It is written once and never changed, and because it lives inside the database it travels with it — rename the database, restore it under a different name, or move it to another SQL Server and TechieCRM still recognises it as the same workspace. Anything TechieCRM remembers per database is tied to that ID, so a rename or a restore does not make it forget.

That matters because the server and database names are not reliable for this. They change on a rename, a restore or a server move, and each change would otherwise look like a brand-new database. TechieCRM keeps the names too, but only as the label you see on screen — for example IslandCRM2017 on PHUKET\SQLSERVER.

Two things worth knowing:

• A restored copy carries the same workspace ID as the original. That is intended: a restored database holds the same records. But it also means that if you restore a copy under a different name to work on separately, TechieCRM regards it as the same workspace as the original, not as a new one.
• If your Login ID cannot create tables, TechieCRM carries on. It does not attempt the write, and does not fill your SQL error log with refusals. It falls back to identifying the database by its server and database name, which works but does not survive a rename or restore — after one of those, anything tied to the workspace is asked again. To avoid that, make the first connection to each database with the source CRM's MASTER ID (or an ID with db_owner), exactly as for the tables above. It only has to happen once.

In MongoDB-only mode there is no SQL database to write to, so no workspace ID is created and no SQL is attempted at all; the local database name is used instead.

One optional step that is NOT automatic — Entrepreneur Dashboard calibration fields

The Entrepreneur Dashboard's per-user calibration settings (income target, stretch goal, planned-work minimum and redline, dashboard period) are stored as user-defined fields inside the source CRM's own field definitions. Because that means writing into the source CRM's configuration — not just adding TechieCRM's own tables — TechieCRM never does it silently. An administrator runs it once, from the folder TechieCRM is installed in:

python -m src.entrepreneur_dashboard_setup --verify     # show what is already there, change nothing
python -m src.entrepreneur_dashboard_setup --prep       # create the fields (safe to re-run)

Sign in for this with the source CRM's MASTER ID or an ID with SQL admin rights. The fields are created in the reserved range 61000–61019 and appear in a folder named Entrepreneur Dashboard on each user's record, where you type each person's targets. Connection details come from the DB_SERVER / DB_NAME / DB_USER / DB_PASSWORD values below, or from --server / --database / --user / --password on the command line. There is also --teardown --confirm, which removes those fields again; it is meant for test databases.

Until this step is run, the dashboard's income and planned-work gauges simply show their "needs setup" state — nothing else in TechieCRM is affected.

Local MongoDB mirror

Sync and backups use a local MongoDB (mongodb://localhost:27017, database techiecrm; override with MONGO_URL / TCRM_LOCAL_DB). Without it the app runs normally — sync, backups and Conversations simply report that the local database isn't running.

Configuration values (.env or environment)

Feature gating and add-ons

The cloud's check-in returns the plan's features; the desktop dims icon-bar modules whose feature is off and gates Text (SMS add-on), cloud sync and cloud backup. Plan scope and add-ons are set in the Admin Portal (Cloud Licenses, SMS Numbers, tenant subscription). Development builds (dev_mode=True in main.py) bypass gating.

Plans and read-only modules

Two plans include a core set of modules rather than all of them, and the two core sets are different:

Business and Corporate include every module.

On the desktop and mobile apps, an Entrepreneur licence keeps read and delete access to the remaining modules: you can open those modules, read every record and delete records (useful when winding a business down or pruning history), but creating and editing there is available on higher plans. TechieCRM simply doesn't show the create/edit buttons in those modules on such a plan, and anything that would write explains itself with a short "Read-only on your plan" note instead.

⚠ On the web portal the same modules currently show an "Upgrade required" page instead of read-only records — the page names your plan, lists the modules it does include, and names the upgrade that unlocks the rest. Whether the web portal should match the apps' read-and-delete behaviour is an open decision (see .coding-team/followup_for_shannon.md #57); until it is made, the apps are the surface for reading history on an Entrepreneur plan.

Where the button disappears, and where you get a note instead

The rule the desktop follows is: an affordance that only writes is hidden; an affordance that is also the only way to READ something stays, and refuses at the point of saving. Reading is never taken away, and neither is deleting.

Hidden on a read-and-delete module — the button is simply not there:

• New / Add buttons everywhere they exist (New Work Order, New employee, New leave request, Add Item, Add Partner, New Project, Add Document, Add Article, New Agreement, New message, New text…), and the equivalent items in the right-click menus.
• Duplicate (Marketing), Run payroll (HR), Evaluate SLAs + compliance now (Compliance & SLA), Schedule Project Plan (Sales, Service), Mark Complete (To-Do), Transform and Set Up Types (Inventory).
• Save, Save As, Add Indicator and the Dashboard Wizard (Dashboards), and the message box and Send button in Messages.

Kept, with a short "Read-only on your plan" note if you try to save:

• SLA Policies… and Compliance Requirements…, HR Setup… and Dashboard ▸ Properties — each of these dialogs is also the only place the list can be READ, and Properties is also where a dashboard is deleted.
• Live Mailbox — it is how you read the mail account, not only how you write.
• Booking an appointment by double-clicking an empty slot in the Calendar — there is no button to hide, so the note appears when you click the slot, before you fill anything in.

Column Setup, filters, sorting, search, Export and Print are never affected: they change what you see, not what is stored.

Upgrading your plan in the web portal lifts the limit immediately — at the next check-in for the apps, and on the next page load in the portal.