LOCIM

• 

• 

• 

• 

Inspiration

Hiring a freelancer should be simple: say what you need, find someone good, pay them when the work is done. In practice, it's a pile of guesswork. Clients have to write a brief they don't know how to write, guess a fair budget, vet strangers, and hope the work matches what they asked for. Freelancers face the mirror image: unclear scope, endless "can you also add…" requests, and the risk of working without being paid.

We noticed that the hard part isn't finding people. It's turning a vague idea into structured work and a safe transaction. AI is good at the first, and PayPal is good at the second. LOCIM puts the two together.

From idea → freelancer → milestone → payment, with AI in the middle.

What it does

LOCIM is an AI-native freelance marketplace. A client types something like "I need a developer to create my landing page for my coffee shop." From there:

1. AI Project Architect turns the sentence into a structured project: title, description, skills, budget, deadline, and milestones. The client can refine it before saving.
2. Explainable matching ranks freelancers and shows why each one fits, not just a score.
3. Escrow through PayPal Sandbox. The client funds one milestone at a time. LOCIM holds the money, and it's paid out to the freelancer only when the client approves the work.
4. AI review of submitted work compares the freelancer's submission against the milestone requirements and flags what looks missing. It is advisory only.
5. Scope-change detection. If the client asks for something extra (in our demo, a CRM), LOCIM checks it against the original scope, calls it new work, and suggests a new milestone with a price. The client decides whether to add it.
6. Payments ledger, dashboard, and disputes. Both sides see progress, escrow, and payouts. If there's a disagreement, funds are frozen until an admin rules.

The AI suggests. The user decides. PayPal moves the money.

How we built it

• Frontend: Next.js 15, TypeScript, Tailwind v4
• Backend: FastAPI, SQLAlchemy 2, Pydantic, Alembic
• Database: PostgreSQL
• AI: Groq (openai/gpt-oss-120b) with structured JSON output
• Payments: PayPal Sandbox (Orders create and capture, server-side)
• Dev environment: Docker Compose, with one command to run everything

We split the AI into specialized services (project planning, matching, work review, scope check) instead of one giant endpoint. Each returns JSON that the backend validates before anything is shown or saved.

PayPal is the backbone of the transaction lifecycle, not just a checkout button. Funding, capture, release, refund, and dispute all map to milestone states, and every payment is tied to a milestone in the ledger. The server creates and captures orders and never trusts a payment status sent from the browser.

The money math

Each milestone carries a platform fee on top, so the freelancer always receives the full milestone amount while the fee covers PayPal's costs. For a milestone of amount $m$ and fee rate $r = 0.10$, the client pays

$$ \text{client pays} = m\,(1 + r), \qquad \text{freelancer receives} = m $$

So the ₱50 Design Mockup in our demo costs the client ₱55. We also enforce that the milestones in a project add up to the budget $B$:

$$ \sum_{i=1}^{n} m_i = B $$

When the AI suggests a new milestone, $B$ grows by exactly that milestone's price (₱200 in the demo, taking the budget from ₱200 to ₱400), and the client sees this before confirming.

Challenges we ran into

• Keeping AI honest and in its lane. An AI that can approve payments is a liability. We made review and scope checks advisory, and every money decision goes through a human. In our demo, the AI says "not enough evidence" when a submission is vague, which is the behavior we want.
• Trusting AI output. Language models sometimes return malformed or unexpected JSON. We validate every response against Pydantic schemas, and POST /api/projects re-checks that milestones sum to the budget instead of trusting the draft.
• Designing escrow with PayPal Orders. Hiring moves no money. Funding captures into LOCIM's merchant account, and release pays the freelancer later. We had to define the states carefully: before the freelancer submits, the client can refund and the project reopens. After that, it's approve or dispute.
• Handling fees fairly. We settled on the platform fee being added on top of each milestone, so freelancers are never short-changed.
• Developing without burning API calls. A deterministic mock AI keeps the UI working offline and in tests, and the real model is used only when a key is set. On startup, the backend also checks the configured model ID and warns if it was retired.
• Sandbox setup. Juggling sandbox buyer and seller accounts, and remembering that Docker only reads .env when a container is created, cost us real debugging time.

Accomplishments that we're proud of

• A complete working loop: describe → structure → match → hire → fund → submit → AI review → approve → payout → payment history
• Scope changes that become priced milestones instead of arguments
• Matching and review that explain themselves
• An admin-ruled dispute flow, and a cap of 3 active projects per freelancer so no one is overloaded

What we learned

• The best use of AI here is structuring intent, not replacing judgment. Planning, matching, and review benefit from AI, while money decisions benefit from a human in the loop.
• Escrow is mostly a state-machine problem. Getting the milestone and payment states right matters more than the checkout itself.
• Strict schema validation turns an unpredictable model into a dependable part of the backend.

What's next for LOCIM

• Move the session token from localStorage to an httpOnly cookie
• Notifications and a project activity timeline
• Richer matching from real portfolio and review signals
• AI-assisted contracts and a fuller dispute workflow
• Additional currencies and payment methods

Note: LOCIM runs on the PayPal Sandbox only. No real money moves in the demo.

Built With

• nextjs
• paypal