Project Structure

A project should be easy to run, change and hand over. Start with a small structure and split it when the boundaries become clear.

What to keep

Keep source, dependency requirements, build configuration, tests and a short README in version control. Keep generated output, local environments and secrets out.

The README should state what the project does, how to run it, how to check a change and which settings it needs. Document commands that work from a fresh checkout.

Interfaces

Separate input handling, core behaviour and external effects. Parsing should produce a representation the rest of the program can trust. Keep database and network operations at clear boundaries.

An interface should specify ownership, valid inputs, output and failure behaviour. Avoid exposing internal data just because it is convenient for one caller.

A design to build: the task engine

Define a small task engine with four states: queued, running, finished and failed. Each task has an identifier, input, state and optional result. A worker claims a queued task by atomically changing its state and generation, then performs the operation and records the outcome.

Keep the scheduler separate from the operation being run. The scheduler owns state transitions; the operation receives input and returns a result. A storage adapter saves tasks without deciding which task runs next.

Add a generation number to each claim. A worker may finish a task only if its generation still matches the stored claim. This gives the design a way to reject a stale worker result after a task has been reassigned. It does not undo external effects the worker already performed.

Decisions worth writing down

Define whether retries are allowed, how cancellation works and which operations are safe to repeat. Decide what happens after a crash between performing an external action and saving its result.

Keep the first version in one process. Add concurrency or persistence only after the state transitions are explicit. See Concurrency and Testing.

Making a contribution

Read the project's contribution instructions, reproduce the issue and keep the change focused. Explain the resulting behaviour and how you checked it. The Open Source Guides cover finding work and communicating with maintainers.