ARC Freelance CRM
Requirements Specification

The system authenticates via username and password. On success the backend creates a session record in the database and returns an httpOnly, Secure, SameSite=Strict cookie containing the session ID. All subsequent API requests from the frontend include this cookie automatically. The backend middleware validates the session on every protected endpoint. Session expiry is 24 hours.

• Passwords stored as bcrypt hashes in PostgreSQL
• No JWT tokens — session record approach with httpOnly cookie
• Middleware rejects unauthenticated requests with HTTP 401
• Frontend redirects to /login on 401 response

Authenticated users can change their password from the Settings page. The endpoint requires the current password for verification before accepting the new password. Password complexity rules apply (minimum 8 characters).

The dashboard displays a scored and ranked list of action items across all active projects. The feed shows the highest-priority items by default ("Top priorities"). A toggle switches to "All actions" showing the complete list.

• Action types displayed: Response Pending (Client), Response Pending (Me), Follow-up, Invoice Due, Project Start, Offer Pending
• Each card: client name, project name, action description, priority score (1-100), due date
• Clicking a card navigates to the relevant project page
• Scores computed by the agent's action_scorer cron (every 1 hour)

Below the action feed, all active projects are shown as cards with color-coded status badges. Nine status states exist: Lead, Talks Initialized, Offer Sent, Offer Accepted, In Progress, Review, Completed, On Hold, Cancelled.

• Mini calendar widget: upcoming 7 days of calendar events
• Recent email activity: last 10 indexed emails with sender, subject, and sentiment indicator
• Financial summary: outstanding invoices total, received this month, pending payments

Create, read, list, and edit clients. No hard-delete — soft-delete via is_deleted flag with deletion reason. Client list is searchable and sortable by: name, status, last contact date, active project count.

• Fields: name (required), notes, email addresses, wildcard patterns
• Email patterns support wildcards, e.g. *@company.com matches all addresses from that domain
• Multiple email addresses per client (ClientEmail table, each can be active or inactive)
• Client detail page tabs: Overview, Projects, Emails, Configuration

Projects belong to a client. A project tracks the complete engagement lifecycle across 9 statuses:

The agent automatically creates action items for each project after analyzing email threads. Each action is scored 1-100. The scoring formula considers:

• Days since last contact with the client
• Email sentiment trend (negative/urgent = higher priority)
• Estimated project value
• Time remaining to deadline
• Waiting_on status (waiting on client = lower urgency than waiting on me)

Each project has a "Deadlines & Events" section displaying calendar events filtered to that project. Users can create, edit, and delete events directly from the project page. Events created here appear on the global Calendar page and sync to Google Calendar. Deletion from the project page removes the local DB record but does not retroactively delete the Google Calendar entry.

The agent's email_sync cron job runs every 15 minutes (configurable via environment). It authenticates via Google OAuth2 and fetches all emails since the last sync timestamp. Emails are matched to clients using their configured email addresses and wildcard patterns.

• Indexed emails receive the "UV-Indexed" label in Gmail
• Original emails are NEVER deleted or moved in Gmail
• Both received and sent emails are indexed (direction flag)
• Deduplication by gmail_id field
• Only plain text body stored — no binary attachments

From any email thread or project action, the user can request an AI-generated reply draft. The agent calls Claude with the full thread context plus a writing style profile learned from the user's sent emails. The draft is editable before sending. Sending uses the Gmail API directly via the backend.

The sentiment_analyzer cron (every 30 minutes) runs Claude on all newly indexed emails. Each email receives a sentiment label: positive, neutral, negative, or urgent. Sentiment is displayed as a badge in thread view and email list.

Calendar page uses FullCalendar.js. Events are color-coded by type. The calendar_sync cron (every 30 minutes) pulls events FROM Google Calendar into the local database. Events created in the ARC app are pushed immediately to Google Calendar.

The calendar_from_emails cron (every 60 minutes) passes recent email threads to Claude using the PARSE_CALENDAR_SYSTEM prompt. Claude identifies meeting dates, deadlines, and reminders mentioned in conversation and returns structured events to add and event titles to remove. Events are created/deleted in both Google Calendar and the local database. Manually triggered from the "Parse from emails" button on the calendar page. No duplicates created (deduplication by title+date).

Offers are created in a tabular form. Each row represents one project phase/step. Columns: Step number, Step name, Description, Hours (decimal), Hourly Rate (PLN), Row Total (auto-calculated). Maximum 15 rows. Grand total auto-updates.

"AI Suggest Steps" calls the agent's suggest_offer_steps endpoint. The agent analyzes the project description and historical offer steps to produce 5-7 suggested steps. The table is fully editable after suggestion.

Offer templates are stored as raw HTML/CSS in the database. The template editor provides a code editor (monospace) with live preview. Template variables use double-brace syntax: {{client_name}}, {{project_name}}, {{steps_table}}, {{total}}, {{date}}. PDF generation uses WeasyPrint on the backend. Multiple templates supported with a default flag.

Each save creates a new version snapshot. All previous versions are stored in the OfferVersions table as JSON snapshots. Any old version can be viewed. The active offer reflects the most recent version.

Invoices can be created standalone or from a linked offer. When created from an offer, offer steps are mapped to invoice line items with quantities and unit prices pre-filled. Invoice numbers are auto-generated. All fields are editable after auto-fill.

An AI analysis side panel is available on the invoice detail page. The agent compares the invoice line items against the original offer and project timeline to surface insights like: "Hours exceeded estimate by X%", "Consider charging for scope changes", "Client historically pays within N days".

Invoice status follows the lifecycle: Draft → Sent → Paid / Overdue / Cancelled. Paid status is set automatically when a matching bank transaction is found by the bank matching agent. Overdue is set when due_date passes without payment.

Users upload bank statement CSV files on the Finance/Import page. Supported formats: Wise, PKO BP, mBank. The backend parses the CSV using pandas, previews the rows, and on confirmation writes them to the BankTransaction table. Import is append-only — no modification or deletion of transactions after import.

After every CSV import, the agent's match_transactions function runs. It matches each BankTransaction to an open Invoice by: reference field substring match, amount within a configurable tolerance (default 1%), and currency match. Matched invoices are automatically marked Paid. Unmatched transactions are flagged for manual review.

Monthly analysis view shows bar chart (income trend), pie chart (client distribution), and tabular breakdown. Tax report view supports configurable period selection, Polish tax reporting format (lump sum ryczalt or general taxation), and export to CSV and/or PDF in Polish or English.

All prompts have hardcoded defaults in arc/agent/app/prompts.py. The _get_prompt(key, default) helper queries the AgentMemory table first (category='prompts'). Custom values stored there override defaults without requiring a restart. The Settings → AI Prompts UI lists all prompts in collapsible cards with monospace editors. Users can save custom values or reset to defaults.

Users can initiate a historical Gmail import from Settings. Configurable ranges: 1, 3, 6, or 12 months. Only one backfill job runs at a time. Re-running the same range skips already-imported emails (deduplication by gmail_id). Only plain text body stored, no attachments.

• BackfillJob record tracks status, range, start/completion time, email count
• Progress visible via polling the job status endpoint
• Completed jobs show an "Emails →" link to /emails in the history table

After backfill completes, all email addresses are assessed for business relevance. Two-pass approach: First, heuristic filter eliminates obvious non-business addresses (noreply, newsletter, service notification patterns). Second, remaining candidates are sent to Claude in a single batch for business relevance scoring. Confidence scores (0.0-1.0) determine how addresses are grouped in the review UI.

Review UI groups addresses by suggested client name. User can edit the suggested name, check/uncheck for inclusion, or mark as "Merge with existing client". Batch client creation creates all approved clients and retroactively links historical emails.

No DELETE endpoints exist in the backend REST API for business data. All "removal" operations use soft-delete via is_active or is_deleted flags. Bank transactions are append-only. Emails are read-only indexed copies. Audit log captures all state changes.

All UI text is available in Polish and English via i18next. Language selection persists per user. Tax reports and financial exports respect the language setting. Polish character support required in PostgreSQL (UTF-8 encoding).