paulserban.eu

Writing Edition

Paul Serban

Writing, snippets & book notes

Vol. 2026

The 5 Hackathon Architecture Mistakes That Cost Teams First Place

Judges notice bad architecture instantly - here's what separates a polished demo from a technical red flag

Introduction

There is a peculiar cruelty to hackathons: you can have the most compelling idea in the room, a slick UI, and a genuinely enthusiastic pitch - and still lose because a judge asked one technical question you couldn't answer well. That question is almost always about architecture.

Judges at serious hackathons - the kind attached to enterprise companies, accelerators, or developer platforms - are typically engineers themselves. They have built systems that fell apart under load. They have inherited codebases that made onboarding feel like archaeology. When they look at your demo, they are not just evaluating what it does; they are pattern-matching against failure modes they have personally lived through. A monolithic function handling authentication, business logic, and database writes all at once reads as a risk, not a time-saving shortcut. The good news is that the architectural signals they are scanning for are learnable, and the mistakes teams make are remarkably consistent.

This article breaks down the five architecture mistakes that most reliably cost hackathon teams placement, explains why each one registers as a red flag to technical judges, and offers concrete approaches you can adopt even within a 24- or 48-hour build window. These are not abstract best practices lifted from a textbook. They are patterns drawn from how distributed systems fail in production and how that failure surface maps onto the shortcuts teams take under time pressure.

Why Architecture Matters in a Time-Constrained Build

It is tempting to think of hackathon architecture as a separate category from real architecture - a simplified, temporary version of the thing that does not need to follow the same rules. This framing is wrong, and it is one of the root causes of the mistakes that follow.

The architecture of a hackathon project matters for two reasons that have nothing to do with whether the code will ever see production. First, it is the most legible signal of engineering judgment that judges have access to. They cannot audit your test coverage or review your git history in depth, but they can ask you why you structured your data model the way you did, or what would happen if two users submitted a form simultaneously. Your answer tells them everything about how you think. Second, architecture shapes whether your demo survives the presentation window. A fragile integration that works on your laptop at 3am may not survive a live demo on spotty conference WiFi with three judges watching.

Judges at well-run hackathons use rubrics that explicitly score technical depth alongside functionality and creativity. When those rubrics ask evaluators to assess "scalability" or "technical implementation," they are not expecting a production-hardened system. They are asking whether the team demonstrated awareness of the constraints and trade-offs their choices introduce. That awareness - or its absence - is visible in five recurring patterns.

Mistake 1: The God Function

The single most common architectural mistake in hackathon code is the God Function: one endpoint, one handler, or one service method that does everything. It authenticates the request, validates the payload, fetches records from the database, runs the core business logic, calls a third-party API, formats the response, and writes a log entry - all in sequence, all in the same scope.

This pattern is understandable under time pressure. Splitting concerns requires upfront thinking about interfaces, and interfaces feel like overhead when you have twelve hours left on the clock. But the God Function creates problems that compound quickly. Error handling becomes nearly impossible to reason about because any of a dozen operations might fail, and the failure modes interact. Testing becomes intractable because there is no seam at which to inject a mock or assert an intermediate state. And in a live demo, any single failure in the chain surfaces as the same opaque error, making recovery or explanation difficult.

The architectural signal judges read from a God Function is not "this team moved fast". It is "this team does not have a mental model for separating concerns". That inference is unfair when it implies laziness - teams are genuinely under pressure - but it is accurate as a predictor of what the codebase would look like in six months. The fix does not require a full service-oriented architecture. Even a simple three-layer split - a route handler that delegates to a service function that delegates to a data access function - demonstrates that the team understands why separation matters.

// ❌ God Function: everything in one handler
app.post("/api/process-order", async (req, res) => {
  const token = req.headers.authorization?.split(" ")[1];
  if (!token) return res.status(401).json({ error: "Unauthorized" });

  let userId;
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
    userId = (decoded as any).sub;
  } catch {
    return res.status(401).json({ error: "Invalid token" });
  }

  const { productId, quantity } = req.body;
  if (!productId || quantity <= 0) return res.status(400).json({ error: "Bad input" });

  const product = await db.query("SELECT * FROM products WHERE id = $1", [productId]);
  if (!product.rows.length) return res.status(404).json({ error: "Not found" });

  const total = product.rows[0].price * quantity;
  await db.query("INSERT INTO orders (user_id, product_id, quantity, total) VALUES ($1,$2,$3,$4)", [userId, productId, quantity, total]);

  const stripeCharge = await stripe.charges.create({ amount: total * 100, currency: "usd", source: "tok_visa" });

  await sendgrid.send({ to: req.body.email, subject: "Order confirmed", text: `Order ${stripeCharge.id} placed.` });

  res.json({ success: true, chargeId: stripeCharge.id });
});

// ✅ Layered: route -> service -> repository
// routes/orders.ts
app.post("/api/process-order", authenticate, async (req, res) => {
  try {
    const result = await orderService.placeOrder(req.user.id, req.body);
    res.json(result);
  } catch (err) {
    handleRouteError(err, res);
  }
});

// services/orderService.ts
export async function placeOrder(userId: string, payload: OrderPayload) {
  const product = await productRepo.findById(payload.productId);
  if (!product) throw new NotFoundError("Product not found");

  const order = await orderRepo.create({ userId, product, quantity: payload.quantity });
  const charge = await paymentGateway.charge(order);
  await notificationService.sendConfirmation(userId, order, charge);

  return { success: true, orderId: order.id };
}

The second version is not significantly more code. But it has visible seams - places where a judge can ask "what happens if the payment fails?" and you can point to a specific function and explain the error propagation clearly.

Mistake 2: Hardcoded Everything

Secrets in source code are the most visible form of this mistake, but hardcoding goes deeper than credentials. Teams that hardcode API base URLs, feature flags, timeout values, retry counts, and environment-specific connection strings are building a system with no configuration surface. When something breaks in the demo environment, there is no lever to pull without editing code and redeploying.

The security dimension is obvious and judges are trained to look for it: a process.env.OPENAI_API_KEY placeholder that was never replaced, a database password embedded in a connection string, an AWS access key in a config.js file that got committed. These are not just bad practices - they are automatic disqualifiers at some companies' internal hackathons and they signal to judges that the team has not internalized the most basic operational security habits. The OWASP Top 10 has listed security misconfiguration and sensitive data exposure in its top five consistently across its published versions, and hardcoded credentials are the textbook example.

The deeper architectural issue is that hardcoding collapses the distinction between the application and its environment. Twelve-factor app methodology - documented at 12factor.net and widely cited in platform engineering - identifies strict separation of config from code as one of the fundamental characteristics of a deployable service. Even if your hackathon project never reaches a second environment, structuring it as if it might demonstrates architectural maturity. Using a .env file with a committed .env.example, centralizing all configuration access through a typed config module, and validating required environment variables at startup adds perhaps thirty minutes of work and completely changes the impression your codebase makes.

// ❌ Hardcoded: brittle, insecure, not portable
const openai = new OpenAI({ apiKey: "sk-abc123youractualkey" });
const DB_URL = "postgresql://admin:password123@localhost:5432/hackdb";
const TIMEOUT_MS = 5000;

// ✅ Config module with validation at startup
// config/index.ts
import { z } from "zod";

const configSchema = z.object({
  OPENAI_API_KEY: z.string().min(1),
  DATABASE_URL: z.string().url(),
  REQUEST_TIMEOUT_MS: z.coerce.number().default(5000),
  NODE_ENV: z.enum(["development", "production", "test"]).default("development"),
});

const parsed = configSchema.safeParse(process.env);
if (!parsed.success) {
  console.error("Invalid configuration:", parsed.error.format());
  process.exit(1);
}

export const config = parsed.data;

This pattern also gives judges something concrete to discuss: when they ask "how would you deploy this?" you can point to the config schema and describe exactly what changes between environments.

Mistake 3: No Error Surface

A common failure mode in hackathon demos is the silent crash. Something goes wrong - the third-party API is rate-limited, the database query returns an unexpected shape, the model inference times out - and the application either hangs indefinitely, returns an inscrutable 500 with no body, or fails in a way that the presenter has to explain with "it was working five minutes ago". This is not just a demo problem. It reflects a fundamental architectural gap: the system has no designed error surface.

Error surface design means thinking deliberately about where failures can occur and what information they should propagate. This includes choosing between throwing exceptions and returning typed error values, deciding what errors are recoverable versus fatal, structuring API responses so that clients always receive a consistent error schema, and making sure that unhandled promise rejections and synchronous exceptions are caught at a boundary and logged with enough context to debug. In a Node.js or Python service, the difference between an application that crashes silently and one that handles errors gracefully is often just a few middleware registrations and consistent try/catch discipline.

Judges who probe this area are asking a question that sounds simple but has real depth: "What happens when X fails?" If your answer is "it would show an error message," and the follow-up is "what error message, where does it come from, and how would you know it happened in production?" - that is when the absence of an error surface becomes visible. A well-designed error response schema, a global error handler middleware, and at least basic structured logging (even to console in a hackathon context) demonstrate that the team has thought about operational reality, not just happy-path functionality.

// Typed error hierarchy
class AppError extends Error {
  constructor(
    public readonly message: string,
    public readonly code: string,
    public readonly statusCode: number,
    public readonly isOperational = true
  ) {
    super(message);
    Object.setPrototypeOf(this, new.target.prototype);
  }
}

class NotFoundError extends AppError {
  constructor(resource: string) {
    super(`${resource} not found`, "RESOURCE_NOT_FOUND", 404);
  }
}

class ExternalServiceError extends AppError {
  constructor(service: string, cause?: Error) {
    super(`${service} is unavailable`, "EXTERNAL_SERVICE_ERROR", 502);
    if (cause) this.cause = cause;
  }
}

// Global error handler middleware (Express)
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  if (err instanceof AppError && err.isOperational) {
    return res.status(err.statusCode).json({
      error: { code: err.code, message: err.message },
    });
  }

  // Unexpected error: log full detail, return generic response
  console.error({ err, path: req.path, method: req.method }, "Unhandled error");
  res.status(500).json({ error: { code: "INTERNAL_ERROR", message: "Something went wrong" } });
});

Even this minimal error hierarchy makes a demo significantly more resilient: when the OpenAI rate limit is hit mid-presentation, the application returns a clean 502 with a readable message rather than hanging or crashing.

Mistake 4: The Synchronous Bottleneck

Hackathon projects built around AI features - LLM inference, image generation, embedding pipelines - frequently share an architectural pattern that causes demos to stall or feel unresponsive: every user action that involves heavy computation is handled synchronously within the HTTP request/response cycle. The user submits a form, the server calls the OpenAI API, waits for the response (often 3-15 seconds), and then returns a result. In a demo with one person and a fast internet connection, this is survivable. In any other context, it is a serious problem.

The architectural concept at stake is the distinction between synchronous request handling and asynchronous task processing. For operations that take more than a few hundred milliseconds, the standard pattern in well-designed systems is to accept the request immediately, enqueue the work, and deliver the result through a polling mechanism or a push notification. This decouples the user experience from the latency of the underlying computation, allows work to be retried if it fails, and prevents the HTTP server from exhausting its connection pool waiting for slow operations to complete. Libraries like Bull or BullMQ in Node.js, Celery in Python, or even a simple in-memory queue for hackathon purposes make this pattern accessible within a short build window.

Judges who ask "how would this scale to a thousand concurrent users?" are listening for whether you understand this distinction. An answer that describes adding more Heroku dynos to the synchronous handler misses the point. An answer that describes separating the request acceptance path from the computation path - even if you did not build the full queue in the hackathon - demonstrates systems thinking that is directly relevant to real-world engineering.

# ❌ Synchronous: blocks the server for every inference call
@app.post("/api/analyze")
async def analyze(request: AnalyzeRequest):
    # This can take 5-15 seconds - server is blocked for entire duration
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": request.text}]
    )
    return {"result": response.choices[0].message.content}


# ✅ Async: accept request, enqueue work, return job ID
from celery import Celery

celery_app = Celery("tasks", broker=os.environ["REDIS_URL"])

@celery_app.task
def run_inference(text: str, job_id: str):
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": text}]
    )
    result = response.choices[0].message.content
    redis_client.setex(f"job:{job_id}", 300, json.dumps({"status": "done", "result": result}))

@app.post("/api/analyze")
async def analyze(request: AnalyzeRequest):
    job_id = str(uuid.uuid4())
    redis_client.setex(f"job:{job_id}", 300, json.dumps({"status": "pending"}))
    run_inference.delay(request.text, job_id)
    return {"jobId": job_id, "statusUrl": f"/api/jobs/{job_id}"}

@app.get("/api/jobs/{job_id}")
async def get_job(job_id: str):
    data = redis_client.get(f"job:{job_id}")
    if not data:
        raise HTTPException(status_code=404, detail="Job not found")
    return json.loads(data)

Even a simplified version of this pattern - using an in-memory queue without Redis for a hackathon - demonstrates the architectural awareness judges are looking for. The conversation you can have about the trade-offs (at-least-once delivery, idempotency, job visibility) is itself a signal of engineering depth.

Mistake 5: The Schema Afterthought

Data modeling is the part of a system that is hardest to change later and easiest to defer in a hackathon. Teams often start with whatever data structure is most convenient for their first feature - a flat JSON blob, a loosely typed document, a table with no foreign keys and no indices - and iterate on top of it without revisiting the model. By demo time, the schema is a sedimentary layer of contradictory assumptions, nullable fields with no clear semantics, and relationships that exist in application code rather than in the data store.

The specific signals judges look for in data modeling vary by domain, but a few anti-patterns recur frequently. Storing structured data as serialized JSON strings inside relational databases gives up the query and consistency guarantees of the RDBMS without gaining the schema flexibility of a proper document store. Using arbitrary string fields for values that should be enumerations or foreign keys creates ambiguity about what values are valid. Designing tables without considering access patterns results in queries that require full table scans on data that will be paginated in the UI. None of these errors requires a large dataset to demonstrate - a judge reviewing your schema can identify them immediately.

A schema that demonstrates good thinking does not need to be complex. It needs to show that the team considered entity relationships, chose appropriate types for each field, and thought about the queries the application would need to run. An entity-relationship diagram, even a rough one drawn during the planning phase and referenced in the README, communicates that the data model was a first-class design artifact rather than an accident of implementation order.

-- ❌ Schema afterthought: ambiguous types, no relationships, no indices
CREATE TABLE posts (
    id TEXT,
    data TEXT,  -- JSON blob with user, content, metadata mixed together
    tags TEXT,  -- comma-separated string
    created TEXT,
    status TEXT  -- "published", "draft", "PUBLISHED", "pub" - inconsistent in practice
);

-- ✅ Intentional schema: clear types, relationships, useful indices
CREATE TABLE users (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email       TEXT NOT NULL UNIQUE,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TYPE post_status AS ENUM ('draft', 'published', 'archived');

CREATE TABLE posts (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    author_id   UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    title       TEXT NOT NULL,
    body        TEXT NOT NULL,
    status      post_status NOT NULL DEFAULT 'draft',
    published_at TIMESTAMPTZ,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE post_tags (
    post_id UUID NOT NULL REFERENCES posts(id) ON DELETE CASCADE,
    tag     TEXT NOT NULL,
    PRIMARY KEY (post_id, tag)
);

-- Indices that match the application's query patterns
CREATE INDEX idx_posts_author_status ON posts(author_id, status);
CREATE INDEX idx_posts_published_at ON posts(published_at DESC) WHERE status = 'published';

The second schema is not dramatically more work to write. But it encodes constraints - the NOT NULL on author, the ENUM on status, the join table for tags - that eliminate entire categories of data integrity bugs. When a judge asks "what happens if two users edit the same post simultaneously?" a schema with an updated_at column and clear ownership semantics gives you something concrete to anchor the discussion.

Trade-offs and When to Break the Rules

Everything above comes with the caveat that architectural judgment is always contextual. There are hackathons where the criteria genuinely reward raw functionality over technical depth, audiences where a slick UI matters more than a clean service layer, and time constraints so severe that even a minimal configuration module is scope that crowds out a core feature. The goal is not to apply these patterns dogmatically but to apply them knowingly.

The most important skill a hackathon team can demonstrate is not perfect architecture but articulate awareness of the trade-offs they made. If you built a God Function because you had four hours left and two features still unimplemented, you can say that directly: "We kept the logic inline to hit our feature targets; in a production system we would extract a service layer here". That kind of response is often more impressive to technical judges than a clean architecture that shipped with fewer features, because it demonstrates that the team can reason about engineering decisions under constraint rather than just following conventions they learned.

The five mistakes covered here sit on a spectrum of effort. Removing hardcoded credentials requires almost no time investment and has high signal value - there is rarely a justification for skipping it. Implementing an async task queue is a more significant architectural change that requires genuine trade-off reasoning. Knowing which mistakes are cheap to fix and which require real scope helps teams prioritize during a build.

Best Practices for Hackathon Architecture

The gap between a fragile hackathon codebase and a architecturally coherent one is not as large as it might seem. A few specific habits account for most of the difference, and most of them cost less than an hour of the build window.

Start with a schema. Before writing application code, spend fifteen minutes sketching your data model on paper or in a tool like dbdiagram.io. Identify your entities, their relationships, and the queries your features will require. This exercise surfaces assumptions early, when they are cheap to change, and gives every team member a shared reference that reduces the coordination overhead of parallel implementation. A schema that was clearly considered is visible in the final codebase even if it was never formally documented.

Use a typed configuration module from the first commit. Create a config.ts or config.py that reads from environment variables, validates required values at startup, and exports a typed object. Every other module imports configuration from this single source. This takes twenty minutes and eliminates an entire category of demo-day failures - the kind where the production API key is missing because someone forgot to copy it to the deployment environment.

Design one error boundary. Choose the outermost layer of your application - the HTTP middleware, the top-level async handler, the main event loop - and make sure that all unhandled errors surface there with enough context to debug. You do not need a sophisticated logging infrastructure. A console.error with the error object, the request path, and a timestamp is enough to diagnose most failures during a live demo.

Separate at least one concern per layer. Even if you cannot build a full three-layer architecture in your timeline, make sure that your route handlers do not contain database queries, and that your database queries do not contain business logic. This single discipline makes your codebase navigable during a demo and gives judges a clear architecture to discuss.

Write one paragraph of architecture notes in your README. Describe the major components of your system, why you chose the primary technology for each, and what you would change with more time. Judges read READMEs. A README that demonstrates architectural self-awareness is a positive signal that requires no additional implementation work.

The 80/20 of Hackathon Architecture

If you apply nothing else from this article, apply these two things. They account for the majority of the architectural gap between projects that impress technical judges and those that do not.

First, eliminate hardcoded credentials and use a validated environment configuration module. This is the single highest-ratio improvement available - it takes under thirty minutes, it eliminates an automatic disqualifier, and it demonstrates basic operational security awareness. There is no situation in which skipping it is the right call.

Second, design your data model before you write application code. Spending fifteen minutes on a schema sketch prevents the most common category of mid-demo failure - the moment when a judge asks about a data integrity scenario and the answer requires explaining why a critical constraint was never enforced. A considered schema is visible in every layer of the application that uses it and changes the character of technical questions you will receive.

The other three mistakes - God Functions, missing error surfaces, and synchronous bottlenecks - are all worth addressing, but they require more effort and involve more genuine trade-offs. The configuration discipline and schema-first approach are nearly free, and their absence is the most reliable predictor of a project that impresses on the surface but falters under technical scrutiny.

Key Takeaways

Five steps you can apply in your next hackathon:

  1. Validate configuration at startup. Use a schema library like Zod (TypeScript) or Pydantic (Python) to validate all environment variables before the application starts. Fail fast with a clear error message if configuration is missing.

  2. Sketch the data model first. Before writing any application code, draw your entities and relationships. Use a migration tool (Flyway, Alembic, or even a single schema.sql file checked into the repo) so the schema is reproducible.

  3. Add a global error handler. Register a catch-all error middleware or top-level exception handler that logs context and returns a consistent error response shape. Test it deliberately before the demo.

  4. Extract at least a service layer. Route handlers should call service functions; service functions should call data access functions. This single layer of indirection makes the codebase navigable and gives you clean seams for error handling.

  5. Document your trade-offs in the README. Write one paragraph describing the architecture and one paragraph describing what you would improve with more time. Judges reward demonstrated awareness of constraints over the pretense of perfection.

Conclusion

Hackathon judges do not expect production-grade systems. They expect evidence of engineering judgment: the ability to make reasonable decisions under constraint, to be aware of the trade-offs those decisions introduce, and to communicate about them clearly. The five mistakes covered here are not failures of effort - teams that make them are usually working just as hard as the teams that place. They are failures of habit: the absence of patterns so foundational that experienced engineers apply them automatically, even in a time-constrained build.

The deeper lesson is that architectural discipline is most valuable precisely when time is short. A codebase with clear separation of concerns, validated configuration, and deliberate error handling is not just better for judges to evaluate - it is faster to debug at 3am when your demo is broken and you have two hours to fix it. The practices that make code legible to judges are the same practices that make code legible to you under pressure. That alignment is not a coincidence. It is why judges use architectural quality as a proxy for engineering judgment in the first place.

The goal is not to spend your hackathon writing infrastructure instead of features. It is to develop the habits that make good architecture almost free - the kind of defaults that emerge naturally from the first keystrokes of a new project, not the kind that require setting aside dedicated time to implement. With practice, configuration validation, layered code organization, and intentional data modeling stop feeling like overhead and start feeling like the only reasonable way to start.

References