Development Guidelines¶

These rules apply to every session, every feature, every change. No exceptions.

Core Mission (Non-Negotiable)¶

Thalian is an AI-powered IT intelligence platform.

Its sole purpose is to surface insights IT teams would otherwise miss and drive smarter IT decisions through AI analysis of cross-platform data.

The defensible value is the cross-platform join — insights that only emerge when data from multiple disconnected systems is held and queried simultaneously. No single source tool can produce these. Thalian can.

Every line of code, every feature, every suggestion must serve this mission.

Rule 1: Preservation First¶

Before implementing ANY new feature, integration, or change (frontend or backend):

Read and understand all existing functioning code in the affected area
Explicitly confirm what existing functionality could be impacted
Do NOT modify, refactor, or touch working code unless directly required by the task
If a change risks breaking existing functionality, stop and flag it before proceeding

When in doubt, do less. Stability of existing functionality takes priority over velocity of new work.

Rule 2: Full Tool Scan on Every New Build¶

Before and after adding any new feature or integration, run a full scan of the codebase to check for:

Convergence — Two or more tools, functions, or components doing the same job
Redundancy — Duplicate data fetching, processing, state management, or rendering logic
Contradiction — Conflicting configs, API calls, data transforms, or business logic

Report findings before writing new code. Resolve all conflicts before merging new work.

Rule 3: Security Checks — Always Run, Never Skip¶

Security checks are mandatory on every new feature AND every existing area touched by a change.

On every new feature, run:¶

Input validation — all user inputs and API payloads sanitized and typed
Authorization check — every query and endpoint scoped to workspace_id; no cross-tenant data leakage possible
Secrets hygiene — no API keys, tokens, or credentials in frontend code, logs, or error messages
Dependency audit — any new npm/pip package scanned for known vulnerabilities before use
Data exposure — confirm no sensitive fields (credentials, PII, tokens) returned to the client unnecessarily
Error handling — errors fail safe; no stack traces or internal details leaked to the client

On every existing area touched, run:¶

Regression security check — confirm the change doesn't weaken an existing auth, validation, or scoping rule
RLS verification — if any Supabase table is touched, confirm Row Level Security policies are still intact and correct
Environment variable audit — confirm no secrets have migrated into code or config files

Hard rules:¶

Every Supabase query must be scoped with workspace_id — no exceptions
Supabase Row Level Security (RLS) must remain enabled on all tables at all times
Never log sensitive data — credentials, tokens, user PII — in any environment
Never expose internal error details to the client
Flag any third-party package added as a potential supply chain risk

Rule 4: AI Analysis Engine Compatibility (Non-Negotiable)¶

Thalian's core value is delivered through its AI analysis engine. Every new data source, integration, or feature MUST:

Produce output that is ingestible by the AI analysis engine
Follow the established data schema and format expected by the engine
Be explicitly wired into the analysis pipeline — passive data collection alone has no value
If a new feature cannot feed the AI engine, it should not be built until that path exists

The buildSystemPrompt() function in functions/api/ai-chat.js is the current ingestion point. Any new data collected must be queryable and injectable there.

If the ingestion path is unclear, stop and ask before building.

Rule 5: Database Schema & Query Rules¶

Core tables (Supabase):¶

Table	Purpose
`workspaces`	Tenant root — all data scopes to this
`workspace_members`	User-to-workspace membership and roles
`profiles`	User profile data
`integrations`	Connected platforms, credentials, sync state
`identities`	Users/accounts synced from IDPs
`applications`	SaaS apps tracked across the workspace
`entitlements`	The core join table — who has access to what app, with what role, last used when
`devices`	Endpoints synced from device managers
`risks`	Named findings generated by the intelligence engine
`actions`	Remediation actions taken or pending
`audit_log`	All platform activity

The `entitlements` table is the intelligence center¶

This is where ~80% of cross-platform intelligence lives. It is the join between identities and applications. New features should query through or write to entitlements wherever access intelligence is involved.

Query rules:¶

Every query must be scoped with workspace_id — this is both a security rule and a data integrity rule
Never query across workspaces
Always use Supabase JS v2 client patterns
RLS is the last line of defense — do not rely on it as the only guard; scope queries in application code too

Rule 6: No Fake Data — Ever¶

This is a hard product rule, not a preference.

Never seed, scaffold, or render placeholder/mock data in any view
Every number, name, count, percentage, or status shown in the UI must come from real workspace data
If real data doesn't exist yet for a view, show a correct empty state — not fake data
This applies to onboarding, dashboard, findings, risks, devices, applications, identities — everywhere
Violating this rule breaks user trust immediately and is not recoverable in the target market

Rule 7: Findings-as-Sentences UX¶

The unit of intelligence display in Thalian is a named finding expressed as a plain-language sentence with a subject and a consequence.

"Sarah Chen has admin access to Salesforce but hasn't logged into Okta in 45 days."
NOT a table row: | sarah@co.com | Admin | Last login: 45d ago |

When building any intelligence, risk, or analysis UI:

Express findings as sentences, not raw data tables
Every finding has a subject (who/what), a condition (what's true), and a consequence (why it matters)
Never default to a data table where a finding sentence is appropriate

Rule 8: Frontend Design Rules¶

Typography (never change these):¶

Syne 700 — headings and wordmark (ALL CAPS, letter-spacing 4px for wordmark)
DM Sans — body text (replaces Outfit, which is deprecated)
DM Mono — ALL metadata: badges, timestamps, counts, percentages, "X of Y" strings, status labels

DM Mono on metadata is a deliberate brand decision. It is not a bug. Do not "fix" it.

See Brand Guidelines for full brand spec, logo files, and color variants.

Color palette:¶

#0a0a0f — dark void (background)
#7c3aed — violet (primary brand)
#14b8a6 — teal (accent)

Logo:¶

Two violet bracket shapes (#7c3aed) flanking a vertical teal bar (#14b8a6)
Font: "F7 The Relay"

UI pattern rules:¶

Blind spot cards are the sole integration connection CTA — no quick-add buttons or sidebar shortcuts
Findings are the center of gravity — every view should lead toward or support named findings
Never add UI chrome that doesn't serve IT intelligence value

Rule 9: Deployment & Infrastructure Awareness¶

Deployment:¶

app.thalian.ai — GitHub repo tori-mf13/thalian-beta — Cloudflare Pages (auto-deploys on git push)
thalian.ai — GitHub repo tori-mf13/thalian-landing — Cloudflare Pages (auto-deploys on git push)
Deployment only happens via git push
No GCP or AWS — do not suggest or scaffold infrastructure for either

Backend:¶

Supabase only
Cloudflare Workers for autosync (thalian-autosync)
Cloudflare R2 for storage if needed

Stack:¶

React (Create React App), Supabase JS v2, Cloudflare Pages Functions
AI: Anthropic Claude API (Sonnet/Opus)
Payments: Stripe

Rule 10: Feature Suggestions — Core Mission Filter¶

When suggesting features, enhancements, changes, or additions, only propose things that:

Directly serve IT teams trying to understand, manage, or act on their environment
Add meaningful signal to the AI analysis engine — more data, better context, cleaner inputs
Reduce manual IT work through automation or intelligent surfacing of information
Improve how insights are delivered, visualized, or acted on by IT operators

Do NOT suggest features that:

Are cosmetic or UX improvements disconnected from IT intelligence value
Add integrations that don't feed meaningful signal into the AI engine
Replicate what generic ITSM or monitoring tools already do without an AI-intelligence angle
Expand scope into non-IT domains without explicit direction from the product owner
Require GCP, AWS, or infrastructure beyond the current Cloudflare + Supabase stack

The filter question: Does this make Thalian smarter, or make IT teams more effective because of Thalian's intelligence?

If the answer is no or unclear — don't suggest it.

Pre-Build Checklist¶

Run through every item before writing any code:

[ ] Existing relevant code reviewed — nothing at risk
[ ] Full tool scan completed — no convergence, redundancy, or contradiction
[ ] Security check scoped — input validation, auth, secrets, RLS, data exposure all considered
[ ] All new queries will be scoped with workspace_id
[ ] RLS policies verified intact on any touched Supabase tables
[ ] No fake or placeholder data introduced anywhere
[ ] AI engine ingestion path identified and confirmed
[ ] Findings expressed as sentences, not raw data tables (where applicable)
[ ] DM Mono preserved on all metadata elements
[ ] Deployment path confirmed as git push only

Post-Build Security Checklist¶

Run through every item after completing a feature before marking it done:

[ ] No secrets, tokens, or credentials in any committed file
[ ] No sensitive data logged in any environment
[ ] No internal error details exposed to the client
[ ] All new Supabase queries scoped with workspace_id
[ ] RLS still enabled and correct on all touched tables
[ ] All user inputs validated and sanitized
[ ] No new npm/pip packages with known vulnerabilities introduced
[ ] No cross-tenant data leakage possible through any new endpoint or query
[ ] Error states fail safe and reveal nothing internal

Summary¶

Rule	One-Line
1. Preservation First	Don't break what works
2. Full Tool Scan	No convergence, redundancy, or contradiction
3. Security Checks	Run before and after every feature and every touched area
4. AI Engine Compatibility	Every feature feeds the engine or it doesn't ship
5. Schema & Query Rules	`workspace_id` on every query, `entitlements` is the core join
6. No Fake Data	Empty states only — never placeholder data
7. Findings-as-Sentences	Named insights in plain language, not data tables
8. Frontend Design Rules	Syne/DM Sans/DM Mono, violet/teal, findings-first UI
9. Deployment Awareness	`git push` only, Cloudflare + Supabase, no GCP/AWS
10. Core Mission Filter	Every suggestion must serve IT intelligence

For visual design specifications referenced in Rule 8, see Brand Guidelines.